Contribute to our documentation

We’re maintaining a single repository for all documents related to the Django CAL-ACCESS project. This section is for anyone who wants to contribute to these documents.

Do I need to know Python (or Django)?

No. But you should be familiar with the syntax of reStructuredText, since that’s the format in which these documents are written.

Which files should I edit?

Generally, you should be editing the .rst files in docs/ directory, rather than any of the .html files in the _build/ directory. The .html files are compiled using Python’s Sphinx documentation framework (for more on this, see Viewing Local Changes).

Viewing changes locally

After you make changes to your local versions of the .rst files in the docs/ directory, you can view your edits as they will appear on ReadTheDocs:

$ make html

This will invoke the sphinx command to compile the .html and .doctree files as they will be when deployed to ReadTheDocs. These files are then saved in docs/_build/html, where you can open them with your favorite web browser and see how they look.

However, you might instead prefer to see your edits as you’re making them:

$ make livehtml

This will start serving the docs on, where you can point your favorite web browser. While the server is running, Sphinx will also detect any change you make to the .rst files and, on save, automatically re-build the .html files.