Project:Auto-documenting python with sphinx: Difference between revisions
DavidNolte (talk | contribs) |
DavidNolte (talk | contribs) |
||
Line 24: | Line 24: | ||
Extensions to be enabled in <code>conf.py</code>: | Extensions to be enabled in <code>conf.py</code>: | ||
< | <syntaxhighlight lang=python> | ||
extensions = [ | extensions = [ | ||
'sphinx.ext.napoleon', | 'sphinx.ext.napoleon', | ||
Line 32: | Line 32: | ||
'sphinxarg.ext', # optional | 'sphinxarg.ext', # optional | ||
] | ] | ||
</ | </syntaxhighlight> | ||
=== ReStructuredText intro === | === ReStructuredText intro === |
Revision as of 17:18, 12 May 2022
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 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.