Configuration

Install sphinx:

$ uv add --dev sphinx sphinx-autodoc-typehints sphinxcontrib.bibtex sphinx-toolbox sphinx-copybutton

To create a documentation folder and initialize the documentation:

$ uv run sphinx-quickstart docs

The folder tree should look like:

$ tree

.
└── docs
    ├── build
    │   ├── doctrees
    │   └── html
    ├── make.bat
    ├── Makefile
    └── source
        ├── conf.py
        ├── index.rst
        ├── _static
        └── _templates

To add the useful extensions in the docs/source/conf.py file:

extensions = [
    'sphinx.ext.autodoc', # documentation in code
    'sphinx.ext.viewcode', # link to source
    'sphinx.ext.napoleon', # google style docstrings
    'sphinx_autodoc_typehints', # DRY type hints
    'sphinx_copybutton', # easy copy code block
    'sphinxcontrib.bibtex', # bibtex style citation
    'sphinx_toolbox.collapse',  # collapsable section
    ]
# bibliography files
bibtex_bibfiles = ['refs.bib']

To set the path to the python source files in the docs/source/conf.py file:

import pathlib
import sys

root = pathlib.Path(__file__).parents[2].resolve()
sys.path.insert(0, root.as_posix())