Building the Documentation

Prerequisites

Install the package together with the documentation dependencies (Sphinx, myst-parser, sphinx-rtd-theme, and sphinxcontrib-mermaid) from an editable checkout of the repository:
```
pip install -e ".[docs]"
```
Using ".[dev]" instead also pulls in the docs group.

Building HTML Documentation

Navigate to the docs directory:
```
cd docs
```
Build the HTML documentation:
```
make html
```
The built documentation will be available in docs/_build/html. Open index.html in your browser to view it.

Building Other Formats

PDF (requires LaTeX):

make latexpdf

Single HTML page:

make singlehtml

EPUB:

make epub

Working with Mermaid Diagrams

Mermaid diagrams are rendered using the sphinxcontrib-mermaid extension. To create or modify diagrams:

Edit the Mermaid diagram code in the RST files
Run make html to build the documentation
Check the rendered diagram in the HTML output

Example Mermaid diagram syntax:

.. mermaid::

   classDiagram
      class NavBase {
          +__init__(*, config=None, **kwargs)
          +logger
          +config
      }
      class DataSet {
          <<abstract>>
          +__init__(*, config=None)
          +_img_name_valid(name)*
          +yield_image_files_from_arguments(args)*
      }
      NavBase <|-- DataSet

Updating API Documentation

The API documentation is automatically generated from docstrings in the code. To update it:

Ensure your code has proper docstrings.
Run make html to rebuild the documentation.

If you add new modules, you may need to update api_reference.rst to include them.

Troubleshooting

If you encounter issues with the documentation build:

Ensure all required packages are installed
Check for syntax errors in RST files
Look for error messages in the build output
Clear the build directory (rm -rf _build) and try again

For Mermaid diagram issues:

Validate your Mermaid syntax using the online Mermaid Live Editor: https://mermaid.live/
Ensure the sphinxcontrib-mermaid extension is properly installed and configured