Adding format/reader documentation pages

Most documentation pages for the supported formats and readers are auto-generated. These pages should not be modified directly. This page explains how to amend/extend this part of the Bio-Formats documentation.

The Bio-Formats testing framework component contains most of the infrastructure to run automated tests against the data repository.

Formats

After checking out source code and building all the JAR files (see Obtaining and building Bio-Formats), the supported formats pages can be generated using the ant gen-format-pages target under the autogen component:

$ ant -f components/autogen/build.xml gen-format-pages

This target will read the metadata for each format stored under format-pages.txt and generate a reStructuredText file for each format stored under formats/<formatname>.txt as well as an index page for all supported formats using Velocity.

The 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:

pagename
The name of the output reStructuredText file. If unspecified, the section header will be used to generate the filename.
extensions
The list of extensions supported for the format
owner
The owner of the file format
developer
The developer of the file format
bsd
A yes/no flag specifying whether the format readers/writers are under the BSD license
versions
A comma-separated list of all versions supported for this format
weHave
A bullet-point list describing the supporting material we have for this format including specification and sample datasets
weWant
A bullet-point list describing the supporting material we would like to have for this format
pixelRating
metadataRating
opennessRating
presenceRating
utilityRating

See 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 pyramid is yes

metadataRating can also be set to a placeholder value, and updated using the ant gen-metadata-ratings target under the autogen component:

$ ant -f components/autogen/build.xml gen-metadata-ratings
reader
A string or a comma-separated list of all readers for this format
mif
set to true if the format can store multiple Images (in OME-XML terminology) or series (in Bio-Formats API terminology)
pyramid
set to yes if the format can store a single image at multiple resolutions
notes
Additional relevant information e.g. that we cannot distribute specification documents to third parties
options
A link to additional reader and writer options documentation where they are available for the format

Dataset structure table

After checking out source code and building all the JAR files (see Obtaining and building Bio-Formats), the summary table listing the extensions for each reader can be generated using the ant gen-structure-table target under the autogen component:

$ ant -f components/autogen/build.xml gen-structure-table

This target will loop through all Bio-Formats readers (BSD and GPL), read their extensions and descriptions and create a reStructuredText file with a table summary of all file extensions.

Readers

After checking out source code and building all the JAR files (see Obtaining and building Bio-Formats), the metadata pages for each reader can be generated using the ant gen-meta-support target under the autogen component:

$ ant -f components/autogen/build.xml gen-meta-support

This target will loop through all Bio-Formats readers (BSD and GPL), parse their metadata support and create an intermediate meta-support.txt file. In a second step, this meta-support.txt file is converted into one reStructuredText page for each reader stored under metadata/<reader>.txt as well as a metadata summary reStructuredText file using Velocity.