Adding format/reader documentation pages
Documentation pages for the supported formats and readers are auto-generated during the build. This page explains how to amend/extend this part of the Bio-Formats documentation.
The supported formats pages are generated as part of the documentation build using maven. The metadata for each format is contained in format-pages.txt and the build generates a reStructuredText file for each format as well as an index page for all supported formats using Velocity.
format-pages.txt is an INI file where each section corresponds to
a particular format given by the section header. Multiple key/values should be
defined for each section:
The name of the output reStructuredText file. If unspecified, the section
header will be used to generate the filename.
The list of extensions supported for the format
The owner of the file format
The developer of the file format
A `yes/no` flag specifying whether the format readers/writers are under
the BSD license
A comma-separated list of all versions supported for this format
A bullet-point list describing the supporting material we have for this
format including specification and sample datasets
A bullet-point list describing the supporting material we would like to
have for this format
See :term:`Ratings legend and definitions`. Available choices are:
`Poor`, `Fair`, `Good`, `Very Good`, `Outstanding`.
The `metadataRating` should be set as follows:
* base `metadataRating` is the smaller of `opennessRating` and `pixelsRating`
* increment `metadataRating` by 1 if any combination of `Instrument.ID` plus `Image.InstrumentRef`,
or `Channel.EmissionWavelength`, or `Channel.ExcitationWavelength` are supported
* increment `metadataRating` by 1 if any SPW metadata is supported or :term:`pyramid` is ``yes``
A string or a comma-separated list of all readers for this format
set to ``true`` if the format can store multiple Images (in OME-XML
terminology) or series (in Bio-Formats API terminology)
set to ``yes`` if the format can store a single image at multiple
Additional relevant information e.g. that we cannot distribute
specification documents to third parties
A link to additional reader and writer options documentation where they
are available for the format
Dataset structure table
The summary table listing the extensions for each reader is generated by the build process reading their extensions and descriptions from all Bio-Formats readers (BSD and GPL). A reStructuredText file with a table summary of all file extensions is created.
The metadata pages for each reader are generated by the build process parsing
their metadata support from all Bio-Formats readers (BSD and GPL). An
meta-support.txt file is created which is then converted
into one reStructuredText page for each reader as well as a metadata summary
reStructuredText file using Velocity.