Adding format/reader documentation pages ======================================== .. _Velocity: http://velocity.apache.org/ 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 :sourcedir:`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 :doc:`building-bioformats`), the supported formats pages can be generated using the :program:`ant` ``gen-format-pages`` target under the :file:`autogen` component:: $ ant -f components/autogen/build.xml gen-format-pages This target will read the metadata for each format stored under :source:`format-pages.txt ` and generate a reStructuredText file for each format stored under :file:`formats/.txt` 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` reader A string or a comma-separated list of all readers for this format notes Additional relevant information e.g. that we cannot distribute specification documents to third parties Dataset structure table ----------------------- After checking out source code and building all the JAR files (see :doc:`building-bioformats`), the summary table listing the extensions for each reader can be generated using the :program:`ant` ``gen-structure-table`` target under the :file:`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 :doc:`building-bioformats`), the metadata pages for each reader can be generated using the :program:`ant` ``gen-meta-support`` target under the :file:`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 :file:`meta-support.txt` file. In a second step, this :file:`meta-support.txt` file is converted into one reStructuredText page for each reader stored under :file:`metadata/.txt` as well as a metadata summary reStructuredText file using Velocity_.