Writing documentation

Writing documentation#

Section author: Xingmin Wang <xingminw@umich.edu>

The documentation is written in reStructuredText and built with Sphinx and the sphinx-book-theme. The example notebooks are rendered by nbsphinx from their stored outputs; they are never executed during the build.

Build locally#

The build dependencies are listed in docs/requirements.txt (the requirements.txt at the repository root adds JupyterLab for running the examples). nbsphinx also needs Pandoc on the PATH.

(mtldp) $ pip install -r docs/requirements.txt
(mtldp) $ sphinx-build -W --keep-going -b html docs/source docs/_build/html
(mtldp) $ python -m http.server -d docs/_build/html 8080

-W turns warnings into errors, which is how the CI builds the site; keep the build free of warnings. docs/Makefile and docs/make.bat are also available; they write to ../../mtldp-website/build.

Publishing#

The site is published at michigan-traffic-lab.github.io/mtldp-doc/build/html by the GitHub Actions workflow .github/workflows/publish-docs.yml. The workflow builds the HTML into build/html/ of a GitHub Pages artifact, adds a root index.html that redirects there, and deploys the artifact; no branch holds the generated files. It runs

  • every time a version tag matching v* is pushed (the tag becomes the version shown in the site title). Creating a release on GitHub creates such a tag, so releases publish as well;

  • on demand from the Actions tab (Run workflow), which publishes the selected branch with the default version of conf.py.

To publish a new version of the documentation:

(mtldp) $ git push origin master
(mtldp) $ git tag v2.21.0
(mtldp) $ git push origin v2.21.0

Then wait for the Publish documentation workflow to finish; the deployment URL is shown on the run, and the site is live a minute later.

The repository setting Settings → Pages → Build and deployment → Source must be GitHub Actions. The workflow uses the github-pages environment with the pages: write and id-token: write permissions it declares; nothing else needs to be configured.

Organisation#

Each folder of docs/source is one chapter of the sidebar:

  • Overview: goals, architecture, the modules and the region design;

  • Getting started: installation and the two walkthroughs (processing raw data, building an application);

  • Reference: the data pipeline, every command line tool and every module of the packages;

  • Tutorials: preparation of the OpenStreetMap and SPaT inputs, installation of fmm;

  • Examples: executable Jupyter notebooks (examples/ at the repository root, linked into docs/source/examples);

  • Applications: research applications built on MTLDP;

  • Developer: this page.

A new feature is documented by describing its command or function in the matching reference page, adding a step to the walkthrough when it changes the workflow, and, when useful, adding an executable notebook to examples/ and to the Examples toctree in index.rst. Describe the current behaviour, not the change: the documentation is a reference, not a changelog.