Project:Auto-documenting python with sphinx

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

1. "Narrative" documentation, written in ReStrucutedText (rst)
2. 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 intro and setup

https://www.sphinx-doc.org/en/master/usage/quickstart.html

https://www.sphinx-doc.org/en/master/tutorial/index.html

Extensions to be enabled in conf.py:

extensions = [
    'sphinx.ext.napoleon',
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',  # optional
    'sphinxarg.ext',    # optional
]

ReStructuredText intro

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Sphinx/RST cheatsheets

https://matplotlib.org/sampledoc/cheatsheet.html

https://sphinx-tutorial.readthedocs.io/cheatsheet

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:

• https://google.github.io/styleguide/pyguide.html
• https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html
• https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

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.