Generating documentation for Mathematica packages

All of the Mathematica packages within the Black Hole Perturbation Toolkit include documentation that is built directly into the Mathematica documentation centre. This is generated using the ApplicationTools package. There are three steps and several caveats to creating new documentation for a package:

1. Consider which documentation to provide

There are three types of documentation pages:

1. Symbol refernce pages: These give an explanation of what the functionality is provided along with some usage examples.
2. Guide pages: These give a summary of the functionality provided by the package in to form of a list of symbols with a brief description for each one.
3. Tutorials: These provide an extended tutorial showing how to use the package.

At the very least, all public Symbols for a package should have reference pages. It is recommended that you also create at least one guide page and one tutorial notebook page for your package.

2. Create source documentation files

The documentation is built from source files using ApplicationTools. These source files are usually stored in a Source subdirectory within the package’s git repository. The source files should be created in the format recognised by ApplicationTools. The best way to learn how to do this is to look at existing packages, for example ReggeWheeler.

3. Build the documentation using ApplicationTools

The documentation is generated by running the GenerateDocumentation.nb notebook within the Source Directory.

Important points

• Tutorials
  • When creating tutorial notebooks, it is a good idea to disable some features that make storage in version control more cumbersome.
  • Tutorial notebooks should not have any output cells, as the input cells will be executed during the documentation build process.
  • The FrontEndVersion for tutorial notebooks should be set to 10.2 for maximum support of older Mathematica versions.
• Symbol Reference Pages
  • By default, ApplicationTools with generate a symbol reference page for any public symbols with usage messages.
  • During the build process, any undocumented symbols, or undocemented symbol options will be listed.
• Building documentation
  • The documentation should be build on the oldest version of Mathematica that you plan to support, which is typically 10.2 for toolkit packages.
  • As part of the build process, an index is generated. This makes it possible to use the search functionality within the documentation centre. Unfortunately, this step fails with versions of Mathematica starting from 11.0.
  • The search index format has changed a number of times since version 11 of Mathematica. Newer versions are able to read the older formats, but the converse is not true. This works by reading in the old index and then generating an index in the new format.
  • Generating a new-format index causes a delay the first time it happens (typically when you first search in the documentation centre, but it may also happen at other times). To avoid this delay, it is recommended when creating a paclet for distribution to created indices for several versions of Mathematica by opening the documentation with those versions. Different versions are stored in different locations and can co-exist within a single paclet.