sigma  1.0.0
Loading...
Searching...
No Matches
Building the Documentation

Sigma's documentation is generated by Doxygen. The API reference is extracted from the doc comments in include/, and the narrative pages are the markdown files in this directory. There is no separate Doxyfile in the repository; the configuration is generated by cmake/cxx_api_docs.cmake at configure time.

Prerequisites

  • Doxygen 1.10.0 or newer. CMake enforces this minimum, and the build also uses Graphviz dot for diagrams.
  • CMake, plus network access on the first configure. The doxygen-awesome-css theme is fetched at configure time.
  • Nothing else. Building only the documentation does not compile the library, so a C++ toolchain, Boost, and Eigen are not required.

Building the documentation

This is what continuous integration runs, and it is the form to use when checking a change before opening a pull request

cmake -Bbuild -H. -DONLY_BUILD_DOCS=ON -DDOCS_FAIL_ON_WARNING=ON
cmake --build build --target sigma_cxx_api
# Documentation will be in ./build/html

The relevant configuration options are

option effect
ONLY_BUILD_DOCS Build the documentation and skip the library entirely
BUILD_DOCS Add the documentation target alongside a normal build
DOCS_FAIL_ON_WARNING Promote Doxygen warnings to errors, as CI does
ENABLE_EIGEN_SUPPORT Also document the Eigen compatibility headers

The generated HTML is committed nowhere. On a merge to the default branch the deploy_dox workflow publishes ./build/html to GitHub Pages, which is what serves https://qcuncertainty.github.io/sigma/.

Adding a page

Drop a new .md file in this directory. Doxygen is handed the whole directory, so the file is picked up with no configuration change, and its title comes from the first level-one heading. Published pages are named after their path, so docs/taylor.md becomes md_docs_2taylor.html.

Automatic pickup does not make a page discoverable. Link it from the root README.md, which is the site's main page, and from whichever sibling pages it belongs with. Use relative paths with the ./ prefix so the links resolve both on GitHub and in the generated site.

Conventions

Match the existing pages, in particular background.md and interval.md.

  • Math uses Doxygen's delimiters, not dollar signs. Inline math is \f$ x \f$, with spaces inside the delimiters.
  • Displayed equations are numbered automatically. Write them as an equation environment carrying a \label, and never type a number by hand

    \f{equation}{ \normalsize
    [a, b] + [c, d] = [a + c,\; b + d]
    \label{eq:iv-add}
    \f}

    MathJax numbers these in order of appearance, so inserting an equation renumbers the rest for free. Numbering is per rendered page and starts at one. The behavior comes from the AMSmath extension plus the autoNumber setting in doxygen-custom/mathjax-config.js, both wired up by cmake/cxx_api_docs.cmake. Use the older \f[ ... \f] form only for display math that should not be numbered.

  • **Refer to equations with \eqref, not a literal number.** Writing Eq. \f$\eqref{eq:iv-add}\f$ renders as Eq. (4) and follows the equation if the numbering shifts. Label names need only be unique within a page; prefixing them per page (eq:iv-, eq:af-, eq:tm-) keeps them readable. \eqref cannot cross pages, because each page numbers independently — describe the other page's equation in words instead.
  • Link to API symbols with [text](@ref sigma::Thing). A bare @ref inside backticks is not a command and will render as literal text.
  • Wrap prose at roughly 80 columns, use only level-one and level-two headings, and end the file with a single newline. pre-commit run --all-files enforces the whitespace rules.

Two failure modes that produce no warning

Doxygen's markdown parser can silently stop interpreting commands partway through a page. Everything after the offending construct is emitted as escaped literal text, so @ref and @section become visible in the rendered output. Neither case produces a Doxygen warning, which means DOCS_FAIL_ON_WARNING will not catch them.

The first is a link whose text wraps across a line break

as described on the [Taylor <-- broken
model](./taylor.md) page.
as described on the
[Taylor model](./taylor.md) page. <-- correct

The second is an unbalanced [ inside inline math, such as the half-open interval \f$ [a, b) \f$. The opening bracket starts a markdown link that is then closed by the next ]( anywhere later in the file. Write \lbrack instead

\f$ [a, b) \f$ <-- broken
\f$ \lbrack a, b) \f$ <-- correct

To check for either, grep the generated HTML for command names that should never survive into the output

# This page is excluded because it discusses the commands by name
ls build/html/md_docs_2*.html | grep -v _r_e_a_d_m_e |
xargs grep -c '@ref\|@section'

Every count should be zero. A nonzero count tells you which page broke, and the offending construct is the last one that rendered correctly on it.