OpenFHE-Numpy Sphinx Documentation Setup

This document summarizes the Sphinx documentation setup for the OpenFHE-Numpy project, including environment, structure, build steps, and troubleshooting.

Sphinx Environment

  • Sphinx: 8.2.3

  • Theme: sphinx-rtd-theme (3.0.2)

  • Extensions: sphinx-autodoc-typehints (2.4.4), napoleon, viewcode, intersphinx, myst-parser (Markdown support)

  • NumPy: For intersphinx linking

Documentation Structure

docs/
    conf.py            # Sphinx configuration
    index.rst          # Main documentation page (with toctree)
    installation.rst   # Installation instructions
    example.rst        # Example usage
    api.rst            # API page (with toctree for modules)
    tensor.rst         # Tensor API documentation
    constructor.rst    # Constructors API documentation
    matrix_arithmetic.rst # Matrix arithmetic API documentation
    enum.rst           # Enum API documentation
    SPHINX_SETUP.md    # This setup guide
    _build/html/       # Generated HTML output
    Makefile           # Build commands

Organization & Navigation

  • index.rst contains the main toctree, referencing all top-level docs: installation, example, api, SPHINX_SETUP.

  • api.rst serves as the API reference landing page, with its own toctree for API modules (tensor, constructor, matrix_arithmetic, enum).

  • All referenced .rst files should exist and be listed in the correct order for navigation.

Configuration Features

  • Extensions: autodoc, napoleon, viewcode, intersphinx, sphinx_autodoc_typehints, myst-parser

  • Theme: Read the Docs theme for consistent styling

  • NumPy-style docstrings: Supported via napoleon

  • Quick start: Usage examples and code snippets

  • API reference: Documents all modules and classes

Building Documentation

cd docs
source ../venv/bin/activate
make clean
make html

Viewing Documentation

Open docs/_build/html/index.html in a web browser, or run:

python -m http.server 8000 -d _build/html

Rebuilding After Changes

make clean && make html

Troubleshooting & Best Practices

  • Ensure all referenced .rst files exist and are included in the correct toctree.

  • If you see import errors for C++ extensions, verify the extension is built and installed in the active Python environment.

  • For docstring formatting issues, use NumPy-style and check indentation.

  • To resolve Sphinx warnings (e.g., missing _static), create the required directories or update conf.py.

  • Always activate the correct virtual environment before building docs.

Updating Structure

To add new API modules, create a new .rst file and add it to the api.rst toctree. Update index.rst if you want it to appear in the main navigation.