Documentation guide

Documentation guide#

Overview#

eagle uses a two-layer documentation system:

  • Doxygen — parses C++/CUDA headers and generates XML from Doxygen docstrings (/** … */ blocks).

  • Sphinx — builds the HTML site from .rst files, pulling in the Doxygen XML via the Breathe extension.

The documentation source lives in docs/. HTML output goes to docs/_build/html/.

Building the docs#

cd docs/
make doxygen html    # Doxygen XML, then the full Sphinx build
make strict          # same, with -W --keep-going (0 warnings required)
make nbexec          # execute every tutorial/example notebook IN PLACE (needs a GPU)
make nbcheck         # refuse the build unless every notebook cell has run
make linkcheck        # crawl every link
make livehtml         # watch + auto-rebuild (requires watchdog)
make clean            # wipe _build/ and _doxybuild/

make linkcheck crawls both internal and external links.

Open _build/html/index.html to view the result. Notebooks under content/userguide/tutorials/, content/userguide/examples/ and content/interop.ipynb are executed locally (make nbexec) and committed with their outputs — the Sphinx build itself never re-executes them (nb_execution_mode = "off" in conf.py); make nbcheck is the gate that catches a notebook committed without having been (re-)run.

Dependencies#

A lightweight conda environment ships as environment-light.yml:

micromamba create -p .envs/eagle_docs -f environment-light.yml -y

Or install manually:

pip install sphinx sphinx-book-theme sphinx-design sphinx-copybutton \
    sphinx-autodoc-typehints myst-nb breathe nbformat nbclient

Doxygen must also be on PATH. Building the Python API reference needs the eagle package importable (pip install -e ./python, see Installation); executing the notebooks additionally needs a CUDA GPU and cupy.

Writing docstrings#

The project uses /** … */ for documented public symbols. The one sanctioned exception is /// @cond INTERNAL / /// @endcond, used to exclude internal-only code from Breathe’s extraction — see Developer guide for where that pattern applies.

Short (single-line) form:

/** @brief Return the raw cudaStream_t handle. */
const cudaStream_t& cuda() const;

Long form (detail block):

/**
 * @brief Re-tune the launch geometry of the instantiated graph.
 *
 * @param size  New logical size (active-sample count) for the replay.
 * @note Does not rebuild the graph; only updates node launch parameters.
 */
void setLogicalSize(const idx_t& size);

Tag order: @brief → @tparam → @param → @return → @throws → @pre / @post → @note → @see.

Hide internal helpers from Breathe with /// @cond INTERNAL / /// @endcond, or place them under a detail/ sub-directory (excluded in Doxyfile.in via EXCLUDE_PATTERNS).

Adding a new page#

  1. Create docs/content/<subfolder>/mypage.rst.

  2. Add to the appropriate toctree in docs/index.rst or the section landing page.

  3. Use relative :doc: paths for cross-folder references:

    :doc:`../api/api_graph`    ← from modules/ to api/

  4. Add a .. seealso:: footer if the page has natural neighbours.

  5. Add a .. contents:: local TOC at the top if the page is long.

  6. Run make doxygen html and check for Sphinx warnings.

Breathe directives#

.. doxygennamespace:: eagle::cuda
   :project: EAGLE
   :members:

.. doxygenfile:: typedefs.h
   :project: EAGLE

.. doxygenclass:: eagle::cuda::Graph
   :project: EAGLE
   :members: