Documentation

Kyle Niemeyer

Oregon State University

2025-02-05

Documenting code and building a documentation website with Sphinx

Documentation

Professor Carole Goble in “Better Software, Better Research”:

One of my favorite #overlyhonestmethods tweets (a hashtag for lab scientists) is Ian Holmes’s “You can download our code from the URL supplied. Good luck downloading the only postdoc who can get it to run, though.”

Value of documentation

• The value and extent of your work is clearer if it can be understood by colleagues.
• Documentation provides provenance for your scientific process, for your colleagues and yourself.
• Documentation demonstrates your skill and professionalism.

Documentation is easier than you think.

• Documentation pays for itself with the time it saves in the long run.
• Documentation requires little effort beyond writing the software itself.

Types of documentation

• Theory manuals
• User and developer guides
• Code comments
• Self-documenting code
• Generated API documentation

User and developer guides

README: sits in top-level directory and contains all the necessary information for installing, getting started with, and understanding the accompanying code.

May be accompanied by other specific files: LICENSE, INSTALL, CITATION, ABOUT, CHANGELOG, CONTRIBUTING

README example

SQUIRREL, version 1.2 released on 2026-09-20

# About

The Spectral Q and U Imaging Radiation Replicating Experimental Library
(SQUIRREL) is a library for replicating radiation sources with spectral details
and Q and U polarizations of superman bubblegum.

# Installation

The SQUIRREL library relies on other libraries:

- The ACORN library www.acorn.nutz
- The TREEBRANCH database format API

Install those before installing the SQUIRREL library. To install the SQUIRREL
library:

./configure
make --prefix=/install/path
make install
...

Comments

Comments provide a way to insert metainformation about code intended for people, right next to the code:

def the_function(var):
    """This is a docstring, where a function definition might live"""
    a = 1 + var # this is a simple comment
    return a

Bad comments

Also possible to pollute code with unnecessary cruft:

def decay(index, database):
    # first, retrieve the decay constants from the database
    mylist = database.decay_constants()
    # next, try to access an element of the list
    try:
        d = mylist[index] # gets decay constant at index in the list
    # if the index doesn't exist
    except IndexError:
        # throw an informative error message
        raise Exception("value not found in the list")
    return d

Useful comments

Code written cleanly will have its own voice. Use intelligent naming to make most lines of code clear without comments, then use comments sparingly to help explain reasons or complicated sections:

def get_decay(index, database):
    """Returns decay constant at index in the database"""
    lambdas = database.decay_constants()
    try:
        lambda_i = lambdas[index] # gets decay constant at index in the list
    except IndexError:
        raise Exception("value not found in the list")
    return lambda

Self-documenting code

Naming: a class, variable, or function name should tell you why it exists, what it does, and how it is used.

Simple functions: functions should be small to be understandable and testable; they should only do one thing.

Consistent style: use a consistent, standardized style; e.g., select variable and function names according to the PEP8 style guide for Python.

Guidelines for naming

# packages and modules are short and lowercase
packages
modules

# other objects can be long
ClassesUseCamelCase
ExceptionsAreClassesToo
functions_use_snake_case
CONSTANTS_USE_ALL_CAPS

# variable scope is *suggested* by style convention
_single_leading_underscore_ # internal to module
single_trailing_underscore_ # avoids conflicts with Python keywords
__double_leading_trailing__ # these are magic, like __init__

Docstrings

docstring: comment placed immediately after a function or class definition, typically enclosed by three pairs of double quotes:

def <name>(<args>):
    """<docstring>"""
    <body>

docstrings are available within Python via help() and iPython’s magic command ?, and Sphinx picks them up.

Docstrings (more)

Make docstrings descriptive and concise; you can explain the arguments of a function, its behavior, and how you intend it to be used.

def power(base, x):
    """Computes base^x. Both base and x should be integers,
    floats, or another numeric type.
    """
    return base**x

Sphinx: automate generating documentation

Sphinx can be used to automate the generation of HTML documentation; we can even use it with GitHub Actions to automatically build and deploy the docs on GitHub Pages.

For now, let’s just make sure your docstrings are suitable for Sphinx.

Numpy-style docstrings

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

Google-style docstrings

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

Getting started with Sphinx

1. pip install sphinx myst-parser
2. mkdir docs
3. cd docs
4. sphinx-quickstart (accept defaults if unsure; answer “yes” for question about autodoc)
5. source directory holds .rst and .md files for user guides, theory manuals, etc., separate from the autogenerated API documentation

Add content for Sphinx

1. In the docs\source directory, add an installation.md file (for example)
2. Add 'myst_parser' to extensions in conf.py
3. Try building with make html
4. Did sphinx find and automatically build docs for your modules? Look for .md files for each module.

Configuration (conf.py)

• Add 'sphinx.ext.autodoc' to extensions
• In extensions, add sphinx.ext.napoleon (for Google/NumPy-style docstring reading) and sphinx.ext.mathjax (if you want LaTeX-based equations), and sphinx.ext.intersphinx for connections to other docs
• Set napoleon_numpy_docstring and napoleon_google_docstring to True/False depending on your docstring style.
• Add an intersphinx_mapping dict to connect to other docs

Configuration

• In conf.py, add autodoc_default_options = {'members': True} and autoclass_content = 'class'
• For each Python module, create a corresponding [modulename].rst file in the docs\source directory. Add .. automodule:: [packagename].[modulename]
• In index.rst, add [modulename] inside the toctree (table of contents)

intersphinx_mapping

intersphinx_mapping = {
  'python': ('https://docs.python.org/3.11', None),
  'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
  'numpy': ('https://docs.scipy.org/doc/numpy/', None),
}

Other Sphinx goodness:

• You can configure it to generate a LaTeX-based PDF (i.e., a single user manual)
• You can have versioned documentation, and also simultaneously have “devel” docs for unreleased changes.

GitHub Actions to automate Sphinx

name: "Sphinx: Render docs"

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
      with:
        persist-credentials: false
    - name: install depedendices
      run : |
        python -m pip install --upgrade pip
        pip install .
        pip install sphinx myst-parser
    - name: Build HTML
      run: |
        cd docs
        make html
    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: html-docs
        path: docs/build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v4
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html

GitHub Actions setup

1. Add sphinx.ext.githubpages to extensions in conf.py
2. Add a docs/requirements.txt file for any dependencies (e.g., myst-parser)
3. On GitHub, Settings -> Pages -> select gh-pages branch in the “Source” dropdown

More on Sphinx - GitHub Actions here: https://www.sphinx-doc.org/en/master/tutorial/deploying.html