Documenting

Documenting#

The documentation for the project is generated using Sphinx. Writing documentation consists of the following components:

  • Writing docstrings for classes and functions as you write code.

  • Adding documentation for the Sphinx-generated documentation on top of what the docstrings provide.

Writing Docstrings#

Every user facing class and function should have a docstring written in NumPy-style, according to the NumPyDoc conventions. A good ocstring

  • Has a short first line, summarizing what the class or method does.

  • Has more detailed description if the complexity of the class or method requires.

  • List all parameters with their explanation.

  • Has a ‘Returns’ section if the returned type is not trivial.

  • Has a ‘Raises’ section if the method raises exceptions.

  • Has an ‘Examples’ section with one or more code snippets if the complexity of the class or method requires. The code snippets should be self-contained in terms of import statements.

Writing Source Files for Sphinx#

Note

This section is under construction.

Building the Documentation#

The project uses Sphinx for documentation. Documentation source files are in docs/source/ and built files go to docs/build/.

Building the documentation:

# Navigate to the docs directory
cd docs

# Build HTML documentation
uv run sphinx-build -b html source build

# Or use make (if available)
uv run make html

# View the documentation by opening docs/build/index.html in a browser