As for all good Python-based projects, our documentation is written in reStructuredText. Some useful links are:
docutils documentation (the autoritative reST reference)
Sphinx’s reST primer
Python’s PEP 257 docstring conventions
Django’s Writing documentation guide
The source of all documentation resides in
.rst files rooted in the
folder, together with code-embedded docstrings.
Building the documentation¶
The documentation is compiled using Sphinx. Note that compiling documentation occurs within the virtual environment with host settings linked.
For the apps, the .rst files are auto-generated using sphinx apidoc through the bash script
To build the documentation, run:
$ cd docs
$ make html
The documentation is then output to folder
docs/_build/html (static html format),
and easily viewable in your browser.
To serve the documentation, use is made of django-sphinxdoc.
The documentation is saved in the local database as a Project with name
SciPost, with slug
SciPost and path
(this project should be manually created in the admin under the
To update the docs, simply run:
$ ./manage.py updatedoc -b SciPost
The documentation is then viewable by navigating to
docs in your browser.