Techwriter at work blog.

Living and writing documentation at Documatt, small team of programmers that do write documentation too.

On this page

Admonitions

Admonitions are specially marked blocks that can appear anywhere an ordinary body element can. Readers will appreciate if you spice up your text with admonitions like tip for extra information or warning to raise their attention.

.. attention:: This is attention.

   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Aenean in dolor id massa convallis eleifend sed eu mauris.

Admonitions in uppercase

Admonitions directives are case insensitive (like all directive and role names). Most documentation and book authors type directives and roles in lowercase.

.. imporant:: Most reStructuredText authors write directives like note in lowercase

However writing admonitions directive in uppercase corresponds with their “raise attention” objective.

.. IMPORTANT:: However writing admonitions uppercase can be considered as
   reasonable exception to "everything-lowercase" rule.

Complex admonition body

Admonition bodies could contain any other reStructuredText elements. As always, you only need to keep correct indentation.

Note

This is a note admonition with complex body containing

  • bullet list

  • item two

And code examples:

$ nano ~/.bash_aliases

The most of time you use admonitions specific to it’s message like warning, note or tip.

Body right after directive

Any text immediately following the directive is interpreted as a directive body. Unlike generic admonition the title of the specific admonition is admonition type i.e. warning, note or tip.

For example, the following note admonition:

.. note:: Specific admonitions like note doesn't have a title

   It means its body begins right after directive name.

is identical to:

.. note::
   Specific admonitions like note doesn't have a title

   It means its body begins right after directive name.

Attention

Attention

This is attention.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Caution

Caution

This is caution

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Danger

Danger

This is danger.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Error

Error

This is error.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Hint

Hint

This is hint.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Important

Important

This is important.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Note

Note

This is note.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Tip

Tip

This is tip.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Warning

Warning

This is warning.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean in dolor id massa convallis eleifend sed eu mauris.

Generic Admonition

Generic admonition are rarely used but has one important benefit over specific ones: you may define admonition title in directive argument. Specific admonitions gets its title automatically set to it’s type (danger has danger as title etc.).

This is generic admonition title

Generic admonition are rarely used but has one important benefit over specific ones: author may define admonition title in directive argument. Specific admonitions gets its type as title (danger has danger as title etc.).

Comments

comments powered by Disqus