Documentation Practices

Introduction to Editing the Sphinx Documentation

Documentation for WESTPA is maintained using Sphinx. Docstrings are formatted in the Numpy style, which are converted to ReStructuredText using Sphinx’ Napoleon plugin, a feature included with Sphinx.

Make sure sphinx and sphinx_rtd_theme are installed on the system. The settings for the documentation are specified in /westpa/doc/conf.py. In order to successfully build the documentation, your system has to statisfy the minimum environment to install WESTPA.

The documentation may be built locally in the _build folder by navigating to the doc folder, and running:

make html

to prepare an html version or:

make latexpdf

To prepare a pdf. The latter requires latex to be available.

Uploading to ReadTheDocs

The online copy of WESTPA Sphinx documentation is hosted on ReadtheDocs. The Sphinx documentations on the main branch are updated whenever the main branch is updated, via a webhook setup on ReadtheDocs and /westpa/.readthedocs.yml. The environment used to build the documentation on the RTD servers are described in /westpa/doc/doc_env.yaml.

In Cases of Major Revisions in Code Base

Currently, each .rst file contains pre-written descriptions and autogenerated sections generated from docstrings via automodule. In cases where the WESTPA code base has significantly changed, the structure of the code base can be regenerated into the test folder by running the following command in the doc folder:

sphinx-apidoc -f -o test ../src/westpa