Adding format/reader documentation pages
========================================

.. _Velocity: http://velocity.apache.org/

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.

Formats
-------

The supported formats pages are generated as part of the documentation build
using :program:`maven`. The metadata for each format is contained in
:doc_source:`format-pages.txt <src/main/resources/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_.

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

.. glossary::

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

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

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.

Readers
-------

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
intermediate :file:`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_.