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 examples:

    • [`example_name.py`](/examples/python/subdir/example_name)

  • 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#

reStructuredText is used in the docstrings for the Python package and in the comment blocks in the examples that are parsed by Sphinx Gallery.

  • Linking to a Sphinx label:

    • :ref:`sec-label-name` (automatic name)

    • :ref:`link text <sec-label-name>` (specified link text)

  • Linking to a Sphinx page:

    • :doc:`/absolute/path` (automatic name)

  • Linking to examples:

    • :doc:`example_name.py </examples/python/subdir/example_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)

  • Citations: @cite authorYYYY will generate a numbered citation like [8], assuming authorYYYY is a key in doc/doxygen/cantera.bib.

  • Equations can be added using LaTeX input bracketed by @f[ and @f].

  • In-line math expressions are enclosed by a pair of @f$ directives, for example @f$ \sin(x) @f$.

On this page
Show Source