MyST in MolSysViewer documentation#

This page summarizes how we use MyST Markdown in MolSysViewer’s documentation, with a focus on admonitions and short, copy-and-paste examples for common patterns.

Recommended admonitions in MolSysViewer#

MolSysViewer documentation uses a small set of MyST admonitions in a consistent way. Below are the patterns we rely on most often.

API documentation#

Use a custom admonition for API links at the beginning of a tutorial:

```{admonition} API documentation
Follow this link for details on arguments, raised errors, and return values:
{func}`molsysmt.basic.get`.
```

Notes and warnings#

Use note for important remarks that users should not skip.
Use warning or danger for situations that can lead to errors or misleading results.

Notes and warnings should normally not be collapsible; they are meant to be read by everyone.

```{note}
Selections always refer to the current form and element level; make sure
you know which form you are working with.
```

Tips and hints#

Use tip or hint for optional advice that can help users work more efficiently, but is not required to follow the main text. These can be made collapsible when they are long or tangential:

```{tip}
:class: tip, dropdown
You can use demo systems from ``molsysmt.systems`` to keep examples short
and reproducible.
```

Default MyST admonitions#

Feel free to use other admonitions. And, if you think they should be frequently used in MolSysViewer documentation, feel free to suggest their inclusion in the above section.

The following is a just a list of what we think are the default MyST admonition.