Building Documentation

This guide explains how to build and maintain the Divi documentation.

Prerequisites

Make sure you have the documentation dependencies installed:

poetry install --with docs

Building the Documentation

Standard Build

To build the HTML documentation:

cd docs
make html

The built documentation will be available in docs/build/html/.

Live Development Server (Recommended for Development)

For active documentation development, use the live reload server:

cd docs
make live

This will: - Automatically rebuild when files change - Serve documentation at http://localhost:8000 - Provide live reloading for faster iteration

Serving Built Documentation

To serve already-built documentation:

cd docs
make serve

Auto-generating API Documentation

The API documentation is automatically generated from docstrings using Sphinx’s autodoc extension. When you add or modify docstrings in your code, the documentation will be updated the next time you build.

Key Files

  • docs/source/conf.py - Sphinx configuration

  • docs/source/index.rst - Main documentation index

  • docs/source/api_reference/ - Auto-generated API docs

  • docs/Makefile - Build commands

Writing Good Docstrings

Follow these guidelines for docstrings that work well with Sphinx:

  1. Use Google-style docstrings (recommended) or NumPy-style

  2. Include type hints - Sphinx will automatically link them

  3. Document all public methods and classes

  4. Include examples where helpful

Example:

def optimize_circuit(self, circuit: Circuit, method: str = "default") -> Circuit:
    """Optimize a quantum circuit using the specified method.

    Args:
        circuit: The quantum circuit to optimize
        method: Optimization method to use

    Returns:
        The optimized circuit

    Raises:
        ValueError: If the method is not supported
    """
    pass

Additional Makefile Commands

The documentation Makefile provides several useful commands:

cd docs
make help          # Show all available commands
make clean         # Remove all build files
make watch         # Watch for changes and rebuild automatically
make check         # Run all quality checks (linkcheck, doctest, coverage)
make linkcheck     # Check for broken links
make install       # Install documentation dependencies