Formatting Documentation#

Most of Cantera’s HTML documentation, with the exception of the C++ API documentation, is generated by Sphinx. The C++ API documentation is generated using Doxygen. The content used to generate these pages comes from several sources:

reStructuredText documents (with the .rst extension), organized under the doc/sphinx subdirectory of the Cantera Git repository.
MyST Markdown documents (with the .md extension), organized under the doc/sphinx subdirectory of the Cantera Git repository.
Docstrings extracted from the Python source code, which are used to generate the Python API docs. These docstrings are parsed as reStructuredText.
Docstrings extracted from the C++ source code, which are parsed by Doxygen. These docstrings are formatted using Doxygen’s syntax, which includes support for its own flavor of Markdown.
Markdown files, organized under the doc/doxygen subdirectory of the Cantera Git repository, processed using Doxygen’s Markdown parser.

This page provides some notes on useful syntax for writing in these various formats.

Useful MyST syntax#

Linking to a Python class: [](#ThermoPhase)
- This only works if there isn’t a Matlab class with the same name!
Linking to a Python class: {py:class}`~cantera.Wall`
- The ~ removes the cantera prefix from the rendered link.
Linking to a C++ class: {ct}`ThermoPhase`
Linking to a Doxygen page: <a href="../cxx/d0/de3/citelist.html">link text</a>
- The number of ../ required depends on how deep the source page is in the hierarchy
Linking to a Sphinx page:
- [](/absolute-subdir/docname) (automatically get the text from docname’s title)
- [link text](relative-subdir/docname) (explicitly specified link text)
- source file extension is optional
Linking to a labeled section:
- [Build Commands](sec-build-commands)
Labeling a section: Above the heading, write:
- (sec-label-name)=
To cite as “according to Smith et al [1999]”: according to {cite:t}`smith1999`
To cite as “blah blah [Smith et al 1999]”: blah blah {cite:p}`smith1999`
Including code from a file (here, drawing directly from the Cantera source tree; the path is relative to the temporary build directory build/doc/sphinx/develop/reactor-integration.md; the number of ../ will vary for files that are at depths within the sphinx directory):
```
:::{literalinclude} ../../../../src/zeroD/ReactorNet.cpp
:start-at: "void ReactorNet::updateState"
:end-before: " ReactorNet::"
:language: c++
:::
```

Useful reST syntax#

Linking to a Sphinx page:
- :doc:`/absolute/path` (automatic name)
Caution on usage of single backticks versus double backticks – the former are only for linking to things using the default role (that is, Python objects)

Useful Doxygen syntax#

Linking to a Sphinx page: [link text](../reference/science/phasethermo/lattice.html)