Writing documentation

Building the documentation

The documentation is built with Sphinx and MyST Markdown. The C++ API reference is extracted by Doxygen and rendered by Breathe. You need Python 3 and Doxygen.

python3 -m venv docs/.venv
docs/.venv/bin/pip install -r docs/requirements.txt
docs/.venv/bin/sphinx-build -W --keep-going docs docs/_build/html

conf.py runs Doxygen itself, so no separate step is needed. Open docs/_build/html/index.html to view the result. -W turns warnings into errors, as in CI. Doxygen warnings fail the build too, for example an @param that names no parameter of the function; they are listed in docs/_doxygen/warnings.log.

On Windows, set up the Python environment in PowerShell:

python -m venv docs/.venv
.\docs\.venv\Scripts\python.exe -m pip install -r docs/requirements.txt

With Doxygen on PATH, build the website and documentation together:

.\scripts\site\build_site.ps1
Start-Process .\_site\docs\index.html

The script uses docs/.venv/Scripts/sphinx-build.exe when available, then sphinx-build on PATH. Set SPHINX_BUILD to use another executable. It replaces _site/ on each run and treats warnings as errors, like scripts/site/build_site.sh. Use -SphinxArgs to pass additional Sphinx options.

Citing sources in articles

Add BibTeX entries to the shared docs/references.bib file. Cite their keys in MyST Markdown with {cite:t} for a citation in the sentence or {cite:p} for a parenthetical citation:

The original method is described by {cite:t}`kerbl2023_3Dgaussians`.
The renderer uses Gaussian splats {cite:p}`kerbl2023_3Dgaussians`.

End each article that cites sources with:

## References

```{bibliography}
:filter: docname in docnames
```

The filter includes only sources cited on that page. Several articles can cite the same entry; each citation links to the bibliography on its own page.

Documenting C++ code

Document the public API in the headers under include/klartraum/, using Doxygen comments:

/**
 * @brief Concatenates two sets of Gaussians every time the graph runs.
 *
 * A's Gaussians come first, so one backend renders and depth-sorts both.
 * The output is per-path.
 *
 * @see GaussianTransform
 */
class GaussianMerge : public GeneralComputation<GaussianMergePushConstants> {
public:
    /**
     * @brief Creates the merge element.
     * @param a First input; its Gaussians come first in the output.
     * @param b Second input, appended after @p a.
     */
    GaussianMerge(GaussianDataPtr a, GaussianDataPtr b);

    uint32_t count;  ///< Number of Gaussians in the merged output.
};
  • Use /** ... */ blocks with @brief, @param, @return, @throws, @note and @see, and ///< for short comments after members.

  • Markdown (lists, code, emphasis) works inside the comments.

  • Comments in .cpp files and on private members stay ordinary // comments; they are not part of the API reference.

  • Longer explanations of concepts belong in these documentation pages, not in header comments.

Adding a class to the API reference

The API pages in docs/api/ list classes explicitly:

```{doxygenclass} klartraum::GaussianMerge
```

Prose pages can link to documented classes with {cpp:class}`klartraum::GaussianMerge` .