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.pyconfiguration filetracks 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:
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.