Auto-documenting python with sphinx

Sphinx is a tool for documenting python packages: https://www.sphinx-doc.org/en/master/ The documentation consists in:

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

Requirements

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 usage

TODO.

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 https://packaging.python.org/en/latest/tutorials/packaging-projects/ and examples such as https://github.com/MaRDI4NFDI/docker-importer/tree/main/setup.py or https://github.com/psf/black/blob/main/setup.py.

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 :members: :undoc-members: :show-inheritance:

https://raw.githubusercontent.com/MaRDI4NFDI/docker-importer/main/docs/

Python docstrings

Document all python code following the google style guide:

also https://peps.python.org/pep-0257/

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: https://github.com/DmytroLitvinov/awesome-flake8-extensions)

flake8 can be enabled as code checker in most editors.

Example

See https://github.com/MaRDI4NFDI/docker-importer/tree/main/docs for a working example.

Project:Auto-documenting python with sphinx

Contents