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,@noteand@see, and///<for short comments after members.Markdown (lists,
code, emphasis) works inside the comments.Comments in
.cppfiles 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` .