How to write API documentation

Devilry is documented 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

You can find lots of examples in the devilry sourcecode. docs/core.models.rst, which documents devilry.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 make html while CWD is docs. Open .build/html/index.html in a browser.

In your shell configfile (.bashrc, .zshrc etc) you will need:

export DJANGO_SETTINGS_MODULE=devilry.projects.dev.settings