How to Use This Documentation

This documentation is generated using Sphinx. While Sphinx is powerful, there are some pitfalls and also some conventions we will establish. It uses reStructuredText (reST) as its markup language.

We will use the NumPy docstring style and this should be the only one enabled.

Here is an example of a properly formatted docstring:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

Refer to the NumPy Guide for more details.

Also folow our style guide for more information on how to write good code and documentation.

How to build the documentation

Please install the requirements from requirements.txt in a env called : .docs-venv/ and then activate it. To build the documentation, navigate to the docs directory and run (assuming you have Linux and a bash shell):

make html

This will generate the HTML documentation in the _build/html directory. You can view it in your web browser, e.g. by using the VS Code extension. Make sure to have Sphinx and the necessary extensions installed in your Python environment.

There is a VS Code extension that can help you generate docstrings.

If you want to generate some nice diagrams, you can uses Mermaid. You can use the Mermaid Live Editor to create your diagrams and then include them in your documentation using the appropriate syntax.