Using the Documentation Generation utilities in Barclay
Under construction. The remaining link placeholders in this doc will eventually be replaced with real links.
The Barclay org.broadinstitute.barclay.help package contains utilities for generating html-based documentation for CommandLinePrograms that are implemented using the Barclay org.broadinstitute.barclay.argparser package. The generation utilities combine the Apache FreeMarker template engine, Barclay org.broadinstitute.barclay.argparser package annotations, and javadoc to produce html output suitable for online help. The documentation generation process is initiated via a javadoc run, and uses a specialized Doclet provided by Barclay.
#Minimum Implementation
It is strongly suggested that implementers that want use this functionality start by cloning the [Need updated links] test files in the test org.broadinstitute.barclay.help package, and using these as a starting project "template". These files contain nearly minimal implementation of the HelpDoclet, DocumentationHandler, and FreeMarker template files needs to generate custom documentation.
To use the Barclay utilities, you need to provide:
- A Java class derived from
org.broadinstitute.barclay.HelpDoclet. This class needs to only override 2 methods: -
- A static start method to return a new instance of your custom Doclet.
-
- An optional method to create an instance of your custom Documentation handler, if you want to provide a custom template.
- An (optional) documentation handler class derived from
org.broadinstitute.barclay.GenericDocumentationHandler. This class should have an override to provide a the name of the custom template. - One or more FreeMarker templates. Barclay contains [default versions] of these templates, but most consumers will want to modify them at least minimally to provide application-specific context in the output.
The DocumentedFeature annotation is how Barclay knows which features in the target project to emit documentation for. The HelpDoclet included in Barclay looks at each class provided via the driving javadoc process, and processes only classes that are annotated with @DocumentedFeature. For each such class, a .html file is emitted that contains the javadoc for that class, and automatically generated documentation for each @Argument or @ArgumentCollection
annotated command line arguments used in that class, as well as for any CommandLinePluginDescriptor-controlled plugins the class also implements CommandLineDescriptorPluginProvider.
There are several points of extensibility for generating Barclay documentation:
- Custom FreeMarker templates.
- Custom JavaDoc tags
- CommandLinePluginDescriptors
[To be completed]
Barclay has the ability to embed application-specific javadoc tags in the FreeMarker template map for use in organizing the documentation output. The custom Doclet can specify a custom Javadoc tag string prefix that will be used by Barclay to identify javadoc tags that should be automatically lifted to, and stored in the FreeMarker template map:
@Override protected String getTagFilterPrefix(){ return "MyTag"; }
These values can then be referenced in the (custom) FreeMarker template.
[To be completed]
The Barclay help test package contains a (Needs updating) simple test example that also illustrates a (nearly) minimal implementation of custom documentation that exercises more of the Barlcay generation. The output generated by the test files can be inspected by looking at the expected test output, included in the repository [here].