Project:Auto-documenting python with sphinx

From MaRDI portal
Revision as of 10:10, 18 May 2022 by DavidNolte (talk | contribs) (→‎Python code checkers =)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Sphinx is a tool for documenting python packages: The documentation consists in:

  1. "Narrative" documentation, written in ReStrucutedText (rst)
  2. automatic API documentation from python docstrings


Python packages:

  • sphinx
  • sphinx-argparse (optional)
  • sphinx-rtd-theme (optional)

Install via pip: pip install -U sphinx sphinx-argparse sphinx-rtd-theme

Getting started with Sphinx

Sphinx intro and setup

Extensions to be enabled in

extensions = [
    'sphinx.ext.todo',  # optional
    'sphinxarg.ext',    # optional

ReStructuredText intro

Sphinx/RST cheatsheets

Sphinx usage


cd docs/
make clean  # optional
make html

Python autodocs

Automatic documentation can be generated from docstrings of python modules. The python modules must be importable via python -c "import <module>". See and examples such as or

An initial module documentation can be generated via sphinx-apidoc -o api path/to/source.

The docstring-based autodocs for a module are included in the RST files as, e.g.,

.. automodule:: mardi_importer.wikidata.EntityCreator

Python docstrings

Document all python code following the google style guide:


Python code checkers

So-called "linters" are helpful also for writing correct docstrings, for instance flake8 and extensions.

Available with pip:

  • flake8
  • flake8-docstrings
  • flake8-rst-docstrings
  • flake8-black
  • flake8-bugbear

(more flake8 extensions:

flake8 can be enabled as code checker in most editors.


See for a working example.