Writing Python Documentation

The very idea of writing documentation sounds tedious to some, this guide aims to remove mental blocks by synthesizing some of the most common tasks for writing documentation.

By the end of the guide you will know:

  • Boostrap Sphinx documentation
  • Configure a theme
  • Document python modules internally with docstrings
  • Reference documented parts of the code: (modules, classes, methods, etc)
  • Make the reverse-reference: your code linking to the documentation
  • Auto-generate API-reference page for python modules
  • Use sphinx.ext.intersphinx to reference external modules documented with Sphinx (e.g.: Flask, requests, boto3)

Annotating Code

Sphinx ships with the sphinx.ext.autodoc which generates the classic API Reference section of many known open source libraries such as Flask, requests and boto3.


Example Code

def make_user(email, password, admin=False, **kwargs):
    """creates structured user data for storage

    :param email: string
    :param password: in plain-text
    :param admin: bool - indicates user has all priviledges
    :param kwargs: extra data

    :returns: a :py:class:`dict` with user data
    data = locals()
    return data

Reference function in a rst document

.. autofunction:: sphinx_bulma_theme.example.make_user

Rendered HTML:

sphinx_bulma_theme.example.make_user(email, password, admin=False, **kwargs)[source]

creates structured user data for storage

  • email – string
  • password – in plain-text
  • admin – bool - indicates user has all priviledges
  • kwargs – extra data

a dict with user data