|
sigma
1.0.0
|
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.
This is what continuous integration runs, and it is the form to use when checking a change before opening a pull request
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/.
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.
Match the existing pages, in particular background.md and interval.md.
Displayed equations are numbered automatically. Write them as an equation environment carrying a \label, and never type a number by hand
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.
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
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
To check for either, grep the generated HTML for command names that should never survive into the output
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.