Configuration
-------------

Install sphinx:

.. code-block:: console

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

To create a documentation folder and initialize the documentation: 

.. code-block:: console

    $ uv run sphinx-quickstart docs

The folder tree should look like:

.. code-block:: console

    $ 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:

.. code-block::

    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:

.. code-block::

    import pathlib
    import sys

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