1 June 2023 by Remco Bouckaert

For BEAST 2 XML, most elements (with a few exceptions, such as the top-level beast element, and map and plate elements) has a java class associated with it, specified in the spec attribute. Since packages are continually being updated, it is not feasible to keep documentation up-to-date, so it can be handy to generate your own for the packages you have installed.

Documenting v2.7 XML

Documentation can be automatically generated using DocMaker, which is part of the BEAST.app package. For each BEAST class, a html page will be generated containing a description of the class (i.e spec attribute) and its inputs (i.e. XML attributes or nested elements), and some information about types of inputs and whether inputs are required. It will produce documentation for classes of installed packages as well: any class declared as a BEASTInterface service in the version.xml file that comes with packages will get its own html page.

DocMaker is an app that can be launched with the AppLauncher that comes with BEAST, or via the command line using

/path/to/beast/bin/applauncher DocMaker /output/dir

where /path/to/beast the path to where you have BEAST installed, and /output/dir the directory to where html files should go. An index.html file is generated in /output/dir that contains a page similar to the one on the online manual. Further, for each class a page is generated documenting that class.

Technical note: All information is obtained through introspection from the @Description annotation of classes and Inputs of each class.

Documenting v2.6 XML

DocMaker behaves slightly different in BEAST v2.6.X, but produces similar output to DocMaker v2.7. To generate documentation for BEAST v2.6.X, run

java -cp /path/to/beast/lib/beast.jar beast.app.DocMaker /output/dir

where /path/to/beast the path to where you have BEAST installed, and /output/dir the directory to where html files should go.

DocMaker in v2.6.X only documents classes in the beast and snap namespace, due to this line, so it behaves a bit difference than the v2.7 version, since only a subset of classes are considered.

For developers, if you change

m_beastObjectNames = PackageManager.find(beast.core.BEASTObject.class, PackageManager.IMPLEMENTATION_DIR);

to

m_beastObjectNames = PackageManager.find(beast.core.BEASTObject.class, new String[]{"beast", "xyz"});

in the v2.6 (not the master) branch, it should pick up classes in the beast as well as ``xyz namespace, where xyz` is the namespace you want to include. You can add as many namespaces as needed.