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.

Learn by example

Sphinx-restructure-text-by-example

Link to relevant docs

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.
• sphinx.ext.autodoc – Include documentation from docstrings.

You can find lots of examples in the devilry sourcecode. docs/developer/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 not_for_deploy/docs/developer/devilry_qualifiesforexam.rst for an example. Note that you can use autodoc to generate API docs from code instead of writing it all like we do in devilry_qualifiesforexam.rst.

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.