Documentation Guidelines

High-quality and consistent documentation is very important at TARDIS. It allows new users to find out how to do something specific using TARDIS, as well as helps developers (like you!) to understand the best practices.

TARDIS uses the popular Python documentation generator Sphinx. Sphinx translates a set of source files (often written in reStructuredText or Jupyter notebooks, see below) to HTML files, automatically producing cross-references, indices, etc. If you haven’t worked with Sphinx before, you should first read their quickstart guide.

Documenting the code you write

When making or adding changes to the functionality of an aspect of TARDIS, an .rst file or Jupyter notebook (.ipynb file) should be created to demonstrate how it works, and that page must then be included in the documentation. This is described in detail in the following sections.

RST Documentation

Documentation not featuring interactive code examples is written in Sphinx’s reStructuredText (see the sphinx documentation). Files written in reStructuredText have a .rst file extension, and are then built as HTML filed by Sphinx during the documentation build. Only the RST file, not the built HTML file, are committed to the repository. Documentation should be clear and concise. See Using TARDIS Widgets as a good example of an RST-generated page.

IPYNB Documentation

Often, code examples can help explain concepts better. The TARDIS utilizes Jupyter notebooks (.ipynb file extension) to demonstrate features of the code package within our documentation. See Quickstart for TARDIS or Energy Packet Initialization for good examples.

TARDIS uses the nbsphinx extension to turn these notebooks into HTML pages in the documentation. During a documentation build, nbsphinx runs all notebooks in the documentation with cleared output and places their output in the HTML. Thus, notebook output must always be cleared before it is submitted to ensure that the notebooks are run by nbsphinx. Running these notebooks during the documentation build helps ensure that the documentation is kept up-to-date, as notebook output will reflect the current state of the TARDIS code. Additionally, if updates in the code are inconsistent with the documentation, the documentation build will return an error, alerting TARDIS developers to the inconsistency.

An added benefit of IPYNB documentation is the ability to have interactive tutorials. All notebooks in the TARDIS documentation feature a button at the top encouraging users to launch the interactive version of the notebook (see the previously mentioned examples). This directs users to the TARDIS repository on Binder, where the notebook can be run using an online Jupyter kernel. Additionally, all notebooks in the Input/Output section of the documentation are automatically linked to on the Tutorials page.

Including Your Page in the TARDIS Documentation

Whether your page is written in reStructuredText or as a Jupyter notebook, it must be included in the TARDIS documentation. This has three steps:

  1. Determine the appropriate location for the page within the documentation. Feel free to reach out to someone in the TARDIS collaboration for help with this step.

  2. Place your file in the corresponding directory in the docs/ directory of the repository. For example, the Using TARDIS Widgets is a subpage of “Visualization Tools and Widgets” under the Input/Output section of the documentation, so it is placed in docs/io/visualization/.

  3. Include your file in the/a toctree of the corresponding index.rst. For example, Using TARDIS Widgets was included in a toctree of docs/io/visualization/index.rst.

Note

When new functions or classes are added to the code, in addition to documentation, docstrings must always be added. Read this section of our code quality guidelines to understand their importance and how they should be formatted. Sphinx uses these docstrings to auto-generate the API documentation for entire TARDIS package. Please make sure that you have correctly formatted the docstrings by checking how the corresponding module’s API looks once you build the documentation.

Building documentation locally

To build TARDIS documentation locally, use the following commands:

cd docs
make html

Note

  • If you’re working on a fresh local copy of the TARDIS repository, you might need to do pip install -e . before executing these commands.

  • Use DISABLE_NBSPHINX=1 make html to disable notebook rendering (fast mode).

  • Use make html NCORES=<number of cores> to have the documentation build in parallel. Using make html NCORES=auto instructs Sphinx to use all of your device’s cores.

  • Use make html SPHINXOPTS="<insert sphinx options>" to include additional sphinx options, which can be found here.

After running this command, you can find the built docs (i.e. HTML webpages) in docs/_build/html. Open the index.html in your browser to see how the documentation looks like with your edits. Navigate to page where you made changes or file that you added to check whether it looks as intended or not.

Additionally, check your terminal for warning messages during the documentation build (often caused by faulty hyperlinks or failing to include the page in the documentation). These should be repaired prior to merging your changes into the documentation. See below for troubleshooting tips.

Sharing the built documentation in your pull request

When proposing changes to the documentation, or the code in general, it is useful to reviewers to see how the documentation will look once your pull request is merged. This is done by adding the build-docs label to your pull request on GitHub. If you do not have permission to add the label, leave a comment in your pull request or contact a senior member of the collaboration and it will be added.

The documentation will be built as soon as the label is added, and any subsequent commits while the label is present will trigger a documentation build. Your built documentation will be available at https://tardis-sn.github.io/tardis/pull/<pull request number>/index.html. It will also be automatically linked to in the comments of the pull request.

Finally, to view the build logs (which will contain warning and error messages), go to the Actions tab in the TARDIS repository, and click on docs in the list of workflows. You can search documentation builds by branch to find your build log.

Troubleshooting Your Documentation

It is important to keep your documentation free of warnings and errors, which can be found in the build logs (locally these will appear in your terminal, and for builds on GitHub see the last paragraph in the above section). On GitHub, these will give you a notification that your documentation build failed. Below are some pointers for resolving these issues:

  • Errors often are a result of notebooks being incompatible with your new code. Make sure notebooks are always updated to reflect your additions.

  • Warnings are often due to incorrect syntax in RST documentation regarding links, section headers, tables of contents, etc. The Sublime and Sphinx Guide is a good resource for learning proper syntax.

  • Warnings can also be because docstrings are not consistent with the numpy docstring format.

  • On GitHub, built documentation files (including .ipynb files built by Sphinx) can be a maximum of 100 MB. You can check the file sizes after a local documentation build in docs/_build/html. Note that image output in notebooks built by Sphinx is by default in SVG format. For detailed images, these images can be very large. If file size becomes a problem, you will need to change the image format for that notebook by placing %config InlineBackend.figure_formats='png2x' in a hidden cell at the beginning of the notebook.

Please reach out for help if you have difficulties resolving issues in your documentation.