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
.. note:: This is a note admonition.
This is the second line of the first paragraph.
- The note contains all indented body elements
following.
- It includes this bullet list.
Or even 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.
.. 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.
.. 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.
.. 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.
.. 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.
.. 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.
.. 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.
.. 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.
.. 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.
.. 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.).
.. admonition:: 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