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
.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 http://127.0.0.1:8000, 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