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.



We have two standard folders for Sphinx documentation:

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


This documentation should never include secret information.


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



Run sphinx-quickstart:



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/

extensions = [

Here are links to the documentation for the extensions:


We use the sphinx_rtd_theme in source/

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


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")


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.


The -f option tells it to overwrite existing files.

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

You should see rst files created in the source folder


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

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.