Part 3: Documentation

Note

Part 3 of 4. This part uses the cookiecutter-git-workshop-documentation repository for its hands-on tasks. It assumes you’ve completed Parts 1 and 2.

See also

A condensed slide deck of this part is available for presenting: Part 3 slides (see Presentation Slides).

Why documentation at all?

Code tells a computer what to do; documentation tells a human why and how. Both matter, but only one of them is optional to a compiler. Writing documentation is worth the effort for a few concrete reasons:

  • it’s essential the moment anyone other than you needs to use your code — including “future you”, who will not remember the details in six months

  • the act of explaining your own design choices to someone else often surfaces problems or unclear decisions you hadn’t noticed while writing it

  • with multiple users, good documentation is the cheapest way to answer the same question once instead of over and over

  • it’s the fastest way back into your own project after time away

The README

The most basic — and most important — piece of documentation is the README, because it’s the very first thing anyone sees when they open your repository. A good README covers:

  • the repository’s purpose (what does this actually do, in one or two sentences?)

  • an installation guide

  • a small code snippet showing typical usage

  • a note on how to contribute

  • the license (if you’re unsure which one, choosealicense.com is a good starting point; this workshop series uses MIT throughout)

reStructuredText

Python’s documentation ecosystem (and this curriculum) is built on reStructuredText (reST), a plain-text markup language — the .rst files you’ve already been reading are written in it. Like Markdown, what you type isn’t quite what you get: the raw source

Features
________

#. Be awesome
#. Make things faster

renders as a proper heading and numbered list once built. A few things to keep in mind while writing it:

  • indentation is meaningful — get it wrong and a block silently stops being part of the list/directive above it

  • blank lines matter, for the same reason

  • it supports far more than headings and lists: tables, images, hyperlinks, citations, footnotes, and arbitrary nested blocks

  • the same source can be built into multiple output formats — HTML, PDF (via LaTeX), ePub, man pages, plain text — without changing a word of the content

See Sphinx’s own reStructuredText primer for a deeper reference once you’re past the basics.

Sphinx

Sphinx is the tool that turns a tree of .rst files into a real, browsable, cross-linked documentation site. It’s the native documentation tool for Python and is what projects like NumPy, SciPy, and scikit-learn use for their own docs. Beyond just converting text to HTML, it:

  • creates links automatically, both within a page and between documents

  • supports extensive customization via its conf.py configuration file

  • tracks your documentation in git right alongside your code, so doc changes go through the same review process as code changes

A Sphinx site is built around one entry point, index.rst, which uses a toctree (table-of-contents tree) directive to declare which other .rst files belong to the site and in what order:

index.rst
Congrats for buying our new super awesome coffee machine. Here we provide
more details on the following topics.

.. toctree::
   :maxdepth: 2
   :caption: Table of Contents

   safety
   quickstart

This one toctree block does three things at once: it pulls the headings from safety.rst and quickstart.rst (up to the given depth) into the navigation, it builds a sidebar menu, and it tells Sphinx these files form one connected site rather than a pile of unrelated pages. To try this yourself, Read the Docs’ Sphinx quick-start guide walks through creating a new Sphinx project from scratch.

Docstrings and autodoc

A docstring is a string literal placed as the first statement inside a module, class, method, or function:

def addition(arg1, arg2):
    """
    This function adds the first and the second argument.

    :param arg1: the first summand
    :type arg1:  float
    :param arg2: the second and last summand
    :type arg2:  float
    :return:     the sum of both summands
    :rtype:      float
    """
    return arg1 + arg2

Docstrings are worth writing directly in the code, rather than in a separate document, for a simple reason: the explanation lives right next to the thing it explains, so when you change the code, updating its documentation is a one-line diff away rather than a separate file you have to remember to update (and that will drift out of sync if you don’t).

Sphinx’s autodoc extension can pull docstrings like the one above directly into your documentation, so you write it once and it appears both as in-code help (help(addition)) and on your docs site. Enable it in conf.py:

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

then reference the function by its import path:

.. autofunction:: adding_numbers.addition.addition

The reST-style :param:/:type:/:return:/:rtype: fields used above are one convention; Google style and NumPy style are two other common docstring conventions you’ll encounter in the wild. The sphinx.ext.napoleon extension teaches autodoc to understand both of those too, so pick whichever convention you like and stay consistent within a project. If you ever see WARNING: autodoc: failed to import function '...' while building, it almost always means the package isn’t installed into your current environment — pip install -e . first.

Continuous deployment and Read the Docs

Continuous deployment extends the CI idea from Part 2: once a merge request is merged, something happens automatically — a new release gets built, an app gets deployed, or, in our case, documentation gets rebuilt and republished. The mechanism behind this is usually a webhook: an API endpoint that one service calls to notify another that something happened (the same basic mechanism that, for example, tells Reddit’s backend to refresh a page after you post a comment). For documentation, your git host calls a webhook on Read the Docs every time you push, which tells RTD to rebuild.

Read the Docs is a hosting service that builds your Sphinx documentation and publishes it as a website, for free for public repositories. The modern way to configure a project is a .readthedocs.yaml file committed to your repository root — it tells RTD which Python version to use and how to install your docs’ dependencies, so the whole build is reproducible and versioned right alongside your code rather than configured by hand through a web UI. Task 3 below has you add one to your own generated package. Once your project is imported into Read the Docs and connected to your repository, pushing to your main branch triggers a new build automatically.