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