Warning, /acts/docs/contribution/documentation_cheatsheet.md is written in an unsupported language. File is not indexed.
0001 # Documentation Markdown Cheatsheet
0002
0003 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:
0004
0005 * The full documentation of the Myst Parser can be found [here](https://myst-parser.readthedocs.io/en/latest/index.html).
0006 * A list of Sphinx directives can be found [here](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives).
0007 * A list of Doxygen directives can be found [here](https://breathe.readthedocs.io/en/latest/directives.html).
0008
0009 ## reStructuredText directives in Myst Markdown
0010
0011 * reStructuredText:
0012
0013 ```text
0014 .. directivename:: arguments
0015 :key1: val1
0016 :key2: val2
0017
0018 This is
0019 directive content
0020 ```
0021
0022 * Myst Markdown (instead of ::: also ``` is possible as delimiter):
0023 ```text
0024 :::{directivename} arguments
0025 ---
0026 key1: val1
0027 key2: val2
0028 ---
0029 This is
0030 directive content
0031 :::
0032 ```
0033
0034
0035 ## Link to API documentation
0036
0037 * Code:
0038
0039 ```text
0040 A link to {class}`Acts::Volume`.
0041 ```
0042
0043 * Result :
0044
0045 A link to {class}`Acts::Volume`.
0046
0047 ## Pull in API documentation
0048
0049 * Code:
0050
0051 ```text
0052 :::{doxygenclass} Acts::Volume
0053 ---
0054 members: center
0055 ---
0056 :::
0057 ```
0058
0059 * Result:
0060
0061 :::{doxygenclass} Acts::Volume
0062 ---
0063 members: center
0064 ---
0065 :::
0066
0067 (cheatsheetlabels)=
0068 ## Cross-referencing and labels
0069
0070 * Setting a label (should be in front of a heading or something like that):
0071
0072 ```text
0073 ## Cross-referencing and labels
0074 (cheatsheetlabels)=
0075 ```
0076
0077 * Referencing a label (with empty `[]` the text of the heading is used):
0078
0079 ```text
0080 Click [here](cheatsheetlabels) to come to the label.
0081 Automatic label text: [](cheatsheetlabels).
0082 ```
0083
0084 Click [here](cheatsheetlabels) to come to the label.
0085 Automatic label text: [](cheatsheetlabels).
0086
0087 ## Info boxes
0088
0089 * Creating boxes (other types are `attention`, `caution`, `danger`, `error`, `hint`, `important`, `tip`, `warning`):
0090
0091 ````text
0092 :::{note}
0093 This is something good to know
0094 :::
0095 ````
0096
0097 * This looks like:
0098
0099 :::{note}
0100 This is something good to know
0101 :::
