Table of Contents

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.

Using the MDN Sphinx Theme project

The documentation uses a Sphinx theme generated from the MDN templates, hosted at https://github.com/mdn/sphinx-theme. This theme is used by MDN and some other groups at Mozilla. If you are going to update the theme, you should switch from the published version specified in docs.txt to a local working copy.

When working with a virtualenv on the host machine, the sphinx-theme project can be checked out anywhere, and installed in the virtualenv:

pip install -e /path/to/sphinx-theme

Now, when the documentation is built, it will use the current theme in the working copy.

Using Docker, the sphinx-theme project must be checked out inside the Kuma repo:

cd /path/to/kuma
git clone git@github.com:mdn/sphinx-theme.git

This will make the sphinx-theme available in Docker at the path /app/sphinx-theme. When generating documentation, adjust the command to install the theme from the working copy:

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 && \
  pip install -e /app/sphinx-theme && \
  cd /app/docs && \
  make html"
python -m webbrowser file://${PWD}/docs/_build/html/index.html

Regenerate the MDN Sphinx Theme template

When regenerating the template, the Kuma version should be the one deployed to production. The assets are loaded from the MDN CDN, and if a non-deployed Kuma commit is used to generate the template, files will be unavailable, which may or may not be obvious when you view the documentation locally.

The MDN Sphinx theme template can be regenerated by Kuma:

docker-compose run --rm -T \
  -e DEBUG=False \
  -e SITE_URL=https://developer.mozilla.org \
  web \
  /app/manage.py generate_sphinx_template \
  > sphinx-theme/mdn_theme/mdn/layout.html

If you are using a virtualenv on the host system, you will need to modify the last line to be the path to your working copy.

In either case, you’ll want to regenerate the documentation to confirm the new layout, and use the browser’s inspector to look for 404s on static assets.

Publish the new MDN Sphinx Theme

To use the new theme in the public documentation:

  1. Commit the new template to sphinx-theme, open a pull request.
  2. Remove the clone of the sphinx-theme from your Kuma repo (Docker method).
  3. After review, merge the PR to the master branch of sphinx-theme.
  4. Tag and publish a new version of mdn-sphinx-theme to PyPI.
  5. Update requirements/docs.txt in kuma, merge to master.