Asides¶

Admonitions
- Admonition
- Attention
- Caution
- Danger
- Error
- Hint
- Important
- Note
- Tip
- Warning
Sidebar
Topic

Admonitions ¶

Admonitions are side notes offset from the main body of text by a box. Examples include “Warning”, “Note” and “Important”. The specific admonition directives attention, caution, danger, error, hint, important, note, tip, and warning are implemented in terms of the generic admonition directive.

PDF Output

In local PDF output, all specific admonitions are rendered in a boxed area, but the generic admonition is rendered slightly differently with a horizontal line above and below.

Admonition ¶

Source:

.. admonition:: Check This Out!

   This is a generic Admonition. It has the custom title "Check This Out!"

   It can have multiple paragraphs.

Result:

Check This Out!

This is a generic Admonition. It has the custom title “Check This Out!”

It can have multiple paragraphs.

Attention ¶

Source:

.. attention::

   This is an Attention admonition.

   It can have multiple paragraphs.

Result:

Attention

This is an Attention admonition.

It can have multiple paragraphs.

Caution ¶

Source:

.. caution::

   This is a Caution admonition.

   It can have multiple paragraphs.

Result:

Caution

This is a Caution admonition.

It can have multiple paragraphs.

Danger ¶

Source:

.. danger::

   This is a Danger admonition.

   It can have multiple paragraphs.

Result:

Danger

This is a Danger admonition.

It can have multiple paragraphs.

Error ¶

Source:

.. error::

   This is an Error admonition.

   It can have multiple paragraphs.

Result:

Error

This is an Error admonition.

It can have multiple paragraphs.

Hint ¶

Source:

.. hint::

   This is a Hint admonition.

   It can have multiple paragraphs.

Result:

Hint

This is a Hint admonition.

It can have multiple paragraphs.

Important ¶

Source:

.. important::

   This is an Important admonition.

   It can have multiple paragraphs.

Result:

Important

This is an Important admonition.

It can have multiple paragraphs.

Note ¶

Source:

.. note::

   This is a Note admonition.

   It can have multiple paragraphs.

Result:

Note

This is a Note admonition.

It can have multiple paragraphs.

Tip ¶

Source:

.. tip::

   This is a Tip admonition.

   It can have multiple paragraphs.

Result:

Tip

This is a Tip admonition.

It can have multiple paragraphs.

Warning ¶

Source:

.. warning::

   This is a Warning admonition.

   It can have multiple paragraphs.

Result:

Warning

This is a Warning admonition.

It can have multiple paragraphs.

Sidebar ¶

Source:

.. sidebar:: Sidebar Title

   Subsequent indented lines comprise
   the body of the sidebar, and are
   interpreted as body elements.

Result:

In HTML: rendered to the right.
In PDF: rendered as a full-width box.

Notes:

Tip: for better rendering, you may want to code the sidebar just before what it relates to, rather than just after.
The version of Sphinx and Sphinx_rtd_theme we use does not seem to render the :subtitle: differently.

References:

https://docutils.sourceforge.io/docs/ref/rst/directives.html#sidebar

Topic ¶

Source:

.. topic:: Topic Title

   Subsequent indented lines comprise
   the body of the topic, and are
   interpreted as body elements.

Result:

Topic Title

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.

Notes:

Result:

In HTML: not rendered all that specially.
In PDF: rendered as a full-width box.

References:

http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic