BF docs improvements

[jamoore]

Remaining issues following new 4.4.5 Docs release on Dec 10th:

Front Page

• Is the link to genomebiology for "OME Data Model" on the front page really the best link? (also first paragraph under Goal of B-F). (Maybe this comes post-BF as a general "OME-XML" doc effort" - YES, not for here)

User

• "Other applications" could use a really nice table possibly with logos.

Developers

Remaining issues to be tackled by Melissa e.g. change MacPort? recommendation to HomeBrew? and make sure all the commands/methods are up to date.

Formats

More text required to explain dataset structure table?

New content (separate PR?)

• Include request for sending example files.

[hflynn]

Added point about adding to developer docs as raised by JM under BF PR 220

[crueden-x]

As requested by hflynn and sbesson, here is the complete list of .txt files from the Bio-Formats repository, what they do and if/where they should move.

Migrate

components/bio-formats/doc/export/*.txt: Documentation on using the Bio-Formats writer API.

components/bio-formats/doc/reader-guide.txt: A guide to coding your own file format reader, written by @mlinkert. Last updated November 2011.

components/bio-formats/doc/using-bioformats.txt: A guide to using the Bio-Formats API, written by @mlinkert. Last updated July 2012.

components/bio-formats/doc/whats-new.txt: A list of changes for each release.

components/scifio/cppwrap/readme-*.txt: Usage instructions for Bio-Formats C++ bindings for various platforms.

Partially migrate

components/bio-formats/doc/metadata-guide.txt: A document explaining how Bio-Formats metadata, which I never finished. Should either be migrated or deleted (with existing content merged into the "Goal of Bio-Formats" page).

components/bio-formats/doc/samples-needed.txt: List of sample data needed for each file format. Last updated July 2012. Merge with individual file format pages (which also have a list of what "We'd like to have"), rather than maintaining separately.

components/bio-formats/doc/meta/*.txt: Autogenerated Trac pages describing the supported metadata fields for each file format. I believe @mlinkert is working on migrating the autogeneration of these to sphinx, so they shouldn't have to be done by hand.

components/bio-formats/doc/testing-procedure.txt: Document describing test procedure. Last updated October 2009, so very likely does not reflect today's actual testing procedure. Delete?

components/test-suite/doc/release-steps.txt: Document describing automated and manual tests performed prior to a Bio-Formats release. Last updated September 2009, and does not reflect today's actual testing procedure. Merge anything relevant to up-to-date release process document, then delete?

**/README.txt, **/readme.txt: These files are automatically displayed by GitHub? when browsing that directory, which means they cannot move. However, some of them might make sense to largely migrate their *contents* to the documentation pages, and then edit the readme itself to provide a link to the main content.

Do not migrate

**/LICENSE.txt: For legal reasons, these licenses must remain. They are a standard of Maven and license-maven-plugin.

**/CMakeLists.txt: These are build files for CMake.

components/forks/**/*.txt: Text files that are part of a forked project. We try to keep our changes to these forked project to an absolute minimum.

components/native/bf-itk-*/slicer-license.txt: Third party copyright attribution.

components/autogen/src/*.txt: Sources for autogenerated documentation.

components/loci-plugins/src/**/*.txt: Configuration files for the Bio-Formats ImageJ plugins.

components/loci-plugins/utils/macros/*.txt: ImageJ example macros.

components/scifio/cppwrap/*.txt: Configuration files defining how to autogenerate the Bio-Formats C++ bindings.

components/scifio/src/loci/formats/*.txt: Configuration files defining available readers and writers.

[hflynn]

There are FAQ links which will need to be updated when that content is migrated to the main docs

[hflynn]

FAQs updated with new links

Replying to hflynn:

There are FAQ links which will need to be updated when that content is migrated to the main docs

[mlinkert]

See ​https://github.com/openmicroscopy/bioformats/pull/324 for some of the developer documentation changes.

[hflynn]

The remaining issue is where to put the request for example files. It would nice to get that added and then I think we are sorted for 4.4.6 - I'm not very taken with the table options in Sphinx, I'm happy to leave the other applications as a list of links for now.

[jmoore]

hflynn: understood on the table front. After adding the "example file request" bit via PR, feel free to close, but let's make sure the OME-XML section has been added to the appropriate ticket.

[hflynn]

See ​https://github.com/openmicroscopy/bioformats/pull/331 for final PR for this ticket

[hflynn]

See #10099 for fixing the front page issue re: OME data model link

[jmoore]

+1