Documentation

Syntax

Click here for reStructuredText syntax

From PEP 257 - Docstring Conventions - Multi-line Docstrings:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero

I think I agree with most of the examples in this document: misc/pep8_cheat.pdf.

I also like some of the ideas in Elements of Python Style. We can watch and see if it becomes accepted.

Initialise

Folders

We have two standard folders for Sphinx documentation:

  1. docs-kb, for internal documentation.
  2. docs-user, for documentation written for the client

Note

This documentation should never include secret information.

Requirements

Add the following to your requirements/local.txt file:

sphinx
sphinx_rtd_theme

Quickstart

Run sphinx-quickstart:

sphinx-quickstart

Extensions

You can accept most of the defaults. These are the exceptions:

Separate source and build directories (y/n) [n]: y
autodoc: automatically insert docstrings from modules (y/n) [n]: y
todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
coverage: checks for documentation coverage (y/n) [n]: y
viewcode: include links to the source code of documented Python objects (y/n) [n]: y

We use the following extensions in source/conf.py:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.doctest",
    "sphinx.ext.todo",
    "sphinx.ext.coverage",
    "sphinx.ext.viewcode",
]

Here are links to the documentation for the extensions:

Theme

We use the sphinx_rtd_theme in source/conf.py:

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Django

If the project uses Django:

# -- Extension configuration -------------------------------------------------

import django
import os
import sys

sys.path.insert(0, os.path.abspath(".."))
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_contact.dev_test")
django.setup()

Note

Update example_contact.dev_test to the settings file for your project.

API Documentation

From One-Off Creation of RST Files

There is a script that you can run to create a directive file per Python module. You should only run this command once to set up the *.rst files.

In the docs directory, run this command to create rst files that document your python modules.

Warning

The -f option tells it to overwrite existing files.

sphinx-apidoc -f -o source/ ../

You should see rst files created in the source folder

Extensions

Module (autodoc)

From sphinx.ext.autodoc

To include python modules in your documentation - i.e. automembered with properties, method names, etc - use the following syntax in your reStructuredText files, placing it where you want the module documented:

.. automodule:: app.modulefile
   :members:

This supports docstrings which are comments wrapped in three speechmarks that should be written after the member you want to autodoc:

class Models():
  """Stores and manage the models signed up to this agency."""

  model_height = model.IntField()
  """The height of the model in metres."""

  def update(self, model):
    """Update this model's info."""

  def expel_model(self, model_pk):
    """
    Expel this model from the agency.

    :param model_pk: The id of the model being expelled.
    :returns: Success message.
    :raises keyError: raises an exception if the model cannot be expelled.
    """