How to write API documentation

Devilry is documented using the Sphinx documentation generator. You need to learn how to write restructured text and how to use the Sphinx-specific restructured text-directives. All of this is documented on the Sphinx website.

The most relevant Sphinx documentation if you are just documenting a python module is:

• reStructuredText Primer
• Module-specific markup
• Include documentation from docstrings
• [Notes, warnings, seealso ...] (http://sphinx.pocoo.org/markup/para.html)
• Cross-references
• Showing code examples
• How to cross link Python code. Note that the :py domain is default, so you do not have to prefix with :py.

You can find lots of examples in the devilry sourcecode. docs/core.models.rst, which documents devilry.apps.core.models.AssignmentGroup, is a good example.

Guidelines

We prefer a howto/examples in addition to API-docs (see docs/devilry_qualifiesforexam.rst for an example.)

How documentation is organized

Documentation lives not_for_deploy/docs/. We have a folder for users, systadmins and developers. Within these directories, each topic is in a separate file. New files must be added to a toctree in the index.rst file of their folder.

Building the documentation

If you have initialized the development environment as described in the README, building the docs is as simple as:

$ workon devilry-django
$ cd not_for_deploy/docs
$ fab docs

Then open not_for_deploy/docs/_build/index.html in a browser.