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, is a good example.

Guidelines

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

How documentation is organized

Documentation lives docs/. Each topic is in a separate file. New files must be added to both toctree and the overview in index.rst.

Required software

You will need a newer version of Sphinx, at least version 1.

Building the documentation

Run devilryadmin.py docs -b to build the docs and open the result in a browser. Run devilryadmin.py without any arguments to see more docs commands.