Writing Documentation
This documentation is generated using sphinx. The docs are automatically built and published to GitHub Pages on a merge into the main branch, using GitHub actions.
These pages are written using ReStructured Text (RST). Here’s a quick primer on the syntax, and a more thorough page from the sphinx documentation.
API Documentation
The API documentation is generated using a sphinx-apidoc, an extension which
parsers the scsr python package and builds api docs from the functions, pulling
details from type annotations and docstrings. We use sphinx.ext.napolean
(docs) to
interpret the docstrings, which expects them to use
Google-style formatting.
All modules within scsr (excluding scsr.cli) will have documentation built
automatically.
CLI Documentation
We use sphinx-argparse to create the documentation for the executables. We’ve
configured it such that it expects markdown-formatted parser documentation
(as RST-formatted text would make the --help text look less readable).
Here’s a quick primer for
writing markdown.
All exectutable files will be documented if they have a submodule within
scsr/cli (and each must have a get_parser() method which returns an
argparse.ArgumentParser)
Adding LaTeX Maths
We use the sphinx.exr.mathjax extension to render maths in the documentation.
This allows for inline \(\LaTeX\) and multiline blocks:
Building the Documentation (Locally)
When updating the docs, it’s important to build them locally to make the building process still works, and to be sure any changes are formatted correctly.
The first time you do this, you’ll need to install the documentation-specific dependencies, which can be done using:
$ pip install -r requirements-docs.txt
Then you can build by running:
$ python doc/build.py && sphinx-build doc doc/_build
doc/build.py creates the template RST files for the API & CLI docs within
./doc, and then sphix-build generates the html pages.
To preview the documenation, open ./doc/_build/index.html in a web browser.