GATK4 Documentation Generation

GATK4 Documentation Generation

GATK online documentation is generated using services provided by the Barclay library. The Barclay services rely on a combination of custom Javadoc doclets; custom FreeMarker templates; Barclay annotations for tagging and annotating command line tools and other classes, and embedded javadoc. The generated documentation, including html files and JSON files for command line tool arguments, is derived by applying a set of rules to extract documentation text from these annotation properties, embedded javadoc, and some custom javadoc tags, described below.

Running the Documentation Generation Process

To generate online documentation for GATK, run the documentation generation process by cloning the GATK repository and running the following command:

    ./gradlew gatkDoc

The resulting html and JSON files are placed in a directory named “gatkDoc”.

Documenting GATK Classes Using Barclay Annotations

The documentation generation system relies on annotations that are defined in Barclay:

• @DocumentedFeature: Tag classes to be included in documentation. A class must have the @DocumentedFeature annotation in order to appear in the output doc. The @DocumentedFeature annotation may optionally include attribute values for summary, groupName, groupSummary etc.
• @CommandLineProgramProperties: Classes that have this annotation can be included in the doc by just including the @DocumentedFeature annotation, with no other attributes. The doc system uses the CommandLineProgramGroup used with @CommandLineProgramProperties to include program group information.
• Annotations used for command line parser arguments: @Argument, @Positional, @Hidden, @Advanced.

Command Line Program Example:

@CommandLineProgramProperties( summary = "Prints reads from the input SAM/BAM/CRAM file to the SAM/BAM/CRAM file.", oneLineSummary = "Print reads in the SAM/BAM/CRAM file", programGroup = ReadProgramGroup.class ) @DocumentedFeature public final class PrintReads extends ReadWalker {...

Since this class has an @CommandLineProgramProperties annotation, the @DocumentedFeature annotation is used only to tag the class for inclusion in the docs. The actual attribute values are pulled from the @CommandLineProgramProperties annotation. Any command line arguments for command line programs are also included in the doc.

Utility Class Example:

@DocumentedFeature( groupName=HelpConstants.DOC_CAT_READFILTERS, groupSummary=HelpConstants.DOC_CAT_READFILTERS_SUMMARY) public final class ReadLengthReadFilter extends ReadFilter implements Serializable{...

Since this class is not a command line program, it has no @CommandLineProgramProperties annotation. In this case, the @DocumentedFeature annotation is used both to tag the class for inclusion in the docs and to populate the actual documentation.

Documentation Construction and Fallback Rules

The doclet scans all classes included in the documentation run to find those that are annotated with @DocumentedFeature. For any such class, the doc system will attempt to use the attribute values directly from the @DocumentedFeature, but will fallback to the @CommandLineProgramProperties values for attribute that are not set in @DocumentedFeature. The detailed documentation text for these classes are derived from the accompanying class javadoc. The javadoc may also include embedded custom GATK tags (see below).

Custom JavaDoc Tags

The GATK doclet defines a custom Javadoc tag prefix (“GATK”) that is used Barclay system to extract custom values from embedded javadoc. Any javadoc tag that uses this prefix will automatically be propagated to the Freemarker map for that object (Note: adding new cutom tags requires must be explicitly included in the JSON output by code).

The GATK4 doc work unit handler currently recognizes and handles one such custom tag: “GATK4.WalkerType”.