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/devilry_qualifiesforexam.rst for an example.)

How documentation is organized

Documentation lives docs/. Each topic is in a separate file. New files must be added to the toctree almost at the bottom of docs/index.rst.

Building the documentation

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

$ cd devenv/
$ bin/sphinxbuilder

Then open devenv/parts/docs/html/index.html in a browser.