Documentation

This documentation is generated and published at Read the Docs whenever the master branch is updated.

GitHub can render our .rst documents as ReStructuredText, which is close enough to Sphinx for most code reviews, without features like links between documents.

It is occasionally necessary to generate the documentation locally. It is easiest to do this with a virtualenv on the host system, using Docker only to regenerate the MDN Sphinx template. If you are not comfortable with that style of development, it can be done entirely in Docker using docker-compose.

Generating documentation

Sphinx uses a Makefile in the docs subfolder to build documentation in several formats. MDN only uses the HTML format, and the generated document index is at docs/_build/html/index.html.

To generate the documentation in a virtualenv on the host machine, first install the requirements:

pip install -r requirements/docs.txt

Then switch to the docs folder to use the Makefile:

cd docs
make html
python -m webbrowser file://${PWD}/_build/html/index.html

To generate the documentation with Docker:

docker-compose run --rm --user $(id -u) web sh -c "\
  virtualenv /tmp/.venvs/docs && \
  . /tmp/.venvs/docs/bin/activate && \
  pip install -r /app/requirements/docs.txt && \
  cd /app/docs && \
  make html"
python -m webbrowser file://${PWD}/docs/_build/html/index.html

A virtualenv is required, to avoid a pip bug when changing the version of a system-installed package.