Notes, warnings, and quotations

Use admonitions, callouts, or alerts to mark up additional information.


Tips

Use the tip directive to highlight information that has a positive effect for users. For example, a tip can be a shortcut or a confirmation.

Tip

This is how a tip appears.

You can also use the hint directive, which appears in the same style.

Hint

Hints and tips appear in the same style.

Topic

The Awesome Theme doesn’t include styles for the topic directive. Use a block quotation or another alert type instead.

Notes

Use the note directive to provide extra information.

Note

This is how a note appears.

To include a list of references, you can use the seealso directive.

To create notes with custom titles, use the admonition directive:

rst
.. admonition:: How to give a note a custom title?

   Enter the custom title after after the ``admonition`` directive.

This renders as:

How to give a note a custom title?

Enter the custom title after the admonition directive.

Warnings

Use a warning directive to alert users about important issues.

Warning

This is a warning.

You can also use the important, attention, or caution directives, which appear in the same style.

Caution

This is how a caution appears.

Important

Important and caution callouts appear in the same style.

Attention

Makes you wonder what the semantic difference between all those callouts are.

Errors

You can use the error directive to inform users about errors..

Error

This is how an error appears.

You can also use the danger directive, which appears in the same style.

Danger

This is how a potentially dangerous step appears.

Version changes

To track when a feature was added, use the versionadded directive.

New in version 5.0: The style for the versionadded directive was added.

To denote an important change between features, use the versionchanged directive.

Changed in version 3.3: Some feature was changed.

To inform users of a deprecated feature, use the deprecated directive.

Deprecated since version 4.0.3: Use the other feature instead.

Block quotations

You can use block quotations to highlight quotes.

“It is my business to know things. That is my trade.”

—Sherlock Holmes