# Formatting Documentation

Most of Cantera's HTML documentation, with the exception of the C++ API documentation,
is generated by [Sphinx](https://sphinx-doc.org). The C++ API documentation is generated
using Doxygen. The content used to generate these pages comes from several sources:

- [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
  documents (with the `.rst` extension), organized under the `doc/sphinx` subdirectory
  of the Cantera Git repository.
- [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/index.html)
  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](https://www.doxygen.nl/manual/docblocks.html). These docstrings are
  formatted using Doxygen's syntax, which includes support for its own flavor of
  Markdown. See also our [style guide for Doxygen comments](sec-style-doxygen).
- 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.

## Describing Units
- Docstrings should generally specify the units of input and output quantities.
- Units should be noted parenthetically, delimited by square brackets, for example
  "The viscosity [Pa·s] of each species in the mixture".
- In Doxygen (C++) documentation, describe the units of simple getters/setters in the
  "brief" documentation that comprises the first line/sentence of the docstring.
- To produce nicely-formatted HTML documentation while avoiding cumbersome notation for
  math (especially in Doxygen and reST), prefer direct use of Unicode characters to
  indicate multiplication (·), exponents (s², m³), and prefixes (μ). Examples:
  [Pa·s], [m²/s], [kmol/m³], [kg/m²/s].
- Use SI abbreviations for common units (m, kg, Pa, V, K, and similar) and full names
  for more specialized units (siemens, poise, coulomb, and similar).
- Much existing Cantera documentation does not follow this style; do not feel obligated
  to update the style of existing docs unless you are making significant changes.

## 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/thermo/species-thermo.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$`.
