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.
• sphinx.ext.napolon - How to write more readable docstrings. We use the google style.

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.