Documentation

Here we provide some high-level guidelines and best practice advice for authors and contributors wishing to build and render the documentation.

Building

The documentation is built using sphinx to parse and render reStructuredText (rst) documents into HTML.

We also use myst-parser, a sphinx and docutils extension to parse and convert MyST to rst, and myst-nb to execute and convert Jupyter Notebooks into sphinx documents.

See also

For configuration details see Makefile and conf.py.

The documentation is built using sphinx-build and the GNU make tool.

Hygiene

Start afresh by performing documentation hygiene to purge various build artifacts.

Table 5: Housekeeping Commands

Make Command	Description
clean	Purge all sphinx-autoapi, sphinx-gallery, sphinx-tags, carousel, and other sphinx-build artifacts.
clean-all	Perform both a clean and clean-cache.
clean-cache	Purge the myst-nb Jupyter cache. See myst-nb configuration for further details.

Build

Build the documentation along with various controls to limit image creation. Note that building the documentation static images and interactive scenes can be resource hungry and time consuming.

Table 6: Build Commands

Make Command	Status	Description
html		Build the full suite of documentation including all images and scenes.
html-docstring		Build the full suite of documentation and only the docstring images and scenes.
html-gallery		Build the full suite of documentation and only the sphinx-gallery images and scenes, which also includes the carousel.
html-inline		Build the full suite of documentation and only inline documentation images and scenes. See #1150.
html-noplot		Build the full suite of documentation with no static images and no interactive scenes.
html-tutorial		Build the full suite of documentation and only the tutorial notebooks.

Render

How-to serve the rendered documentation for inspection in a local browser.

Table 7: Render Commands

Make Command	Description
serve-html	Start a local HTTP server on port 11000 to view the rendered documentation. This is necessary in order to support interactive scenes.

Test

Perform documentation quality assurance.

Table 8: Test Commands

Make Command	Description
doctest	Execute sphinx.ext.doctest to test snippets within the documentation.
linkcheck	Check the integrity of all external links referenced within the documentation using the sphinx linkcheck builder.