Documentation Markdown Cheatsheet

Below there are some snippets for creating documentation with the Myst Markdown parser. Some examples might not work correctly locally if you did not build the full API documentation with make docs-with-api. Some links for further reading:

  • The full documentation of the Myst Parser can be found here.

  • A list of Sphinx directives can be found here.

  • A list of Doxygen directives can be found here.

reStructuredText directives in Myst Markdown

  • reStructuredText:

.. directivename:: arguments
   :key1: val1
   :key2: val2

   This is
   directive content
  • Myst Markdown (instead of ::: also ``` is possible as delimiter):

:::{directivename} arguments
---
key1: val1
key2: val2
---
This is
directive content
:::

Pull in API documentation

  • Code:

:::{doxygenclass} Acts::Volume
---
members: center
---
:::
  • Result:

class Volume : public Acts::GeometryObject

It inherits from GeometryObject for geometry identification.

Base class for all volumes inside the tracking realm, it defines the interface for inherited Volume classes regarding the geometrical information.

Subclassed by Acts::CylinderVolumeStack, Acts::TrackingVolume

Public Functions

const Vector3 &center() const

returns the center of the volume

Cross-referencing and labels

  • Setting a label (should be in front of a heading or something like that):

## Cross-referencing and labels
(cheatsheetlabels)=
  • Referencing a label (with empty [] the text of the heading is used):

Click [here](cheatsheetlabels) to come to the label.
Automatic label text: [](cheatsheetlabels).

Click here to come to the label. Automatic label text: Cross-referencing and labels.

Info boxes

  • Creating boxes (other types are attention, caution, danger, error, hint, important, tip, warning):

:::{note}
This is something good to know
:::
  • This looks like:

Note

This is something good to know