Admonition Messages#


Admonitions are a particular group of reST directives.

Admonitions purpose is to highlight a message to the user with colour and formatting.

How-to#

The code block below demonstrates the syntax for one of the available admonition styles and is the “note” directive.


1.. note:: Text in the title bar or
2    on the first row will be displayed
3    in the message body, with one exception.  The general purpose
4    :sep:`.. admonition::` includes text in the Title bar as a title.
5
6    See :ref:`Admonition <reference-admonition>` for details.
7
8    Here is the note admonition...

Pay attention to the spacing of the highlighted message block line.

As you can see below, this renders correctly.

Note

Text in the title bar or on the first row will be displayed in the message body, with one exception. The general purpose .. admonition:: includes text in the Title bar as a title.

See Admonition for details.

Here is the note admonition…

 1.. note:: Text in the title bar or
 2    on the first row will be displayed
 3    in the message body, with one exception.  The general purpose
 4    :sep:`.. admonition::` includes text in the Title bar as a title.
 5
 6    See :ref:`Admonition <reference-admonition>` for details.
 7
 8        Here is the note admonition...
 9
10 Here is the note admonition...

Here the spacing of the highlighted message block lines doesn’t produce the desired layout for this example.

As you can see below, this does not render correctly.

Note

Text in the title bar or

on the first row will be displayed in the message body, with one exception. The general purpose .. admonition:: includes text in the Title bar as a title.

See Admonition for details.

Here is the note admonition…

Here is the note admonition…

Reference#


Many other examples follow below, in the How it Looks and reST syntax tabs.

Admonition#

A generic, Titled admonition

This is some random text on the topic.

1.. admonition:: A generic, Titled admonition
2
3   This is some random text on the topic.

Warning

Admonition directive Title is required!

The syntax must look like this .. admonition:: Some User Title. or this particular style may not render correctly.

See also#

See also

Admonitions in docutils.

1 .. seealso::
2
3    Admonitions in `docutils <http://docutils.sourceforge.net/0.7/docs/ref/rst/directives.html#admonitions>`__.

Note#

Note

Here is a short note.

1.. note::
2
3    Here is a short note.

Tip#

Tip

A tip is an idea that can help.

1.. tip::
2
3   A tip is an idea that can help.

Hint#

Hint

A hint is an indirect suggestion or advice.

1.. hint::
2
3  A hint is an indirect suggestion or advice.

Important#

Important

Important information that should be considered.

1.. important::
2
3  Important information that should be considered.

Caution#

Caution

Caution dragons may live here.

1.. caution::
2
3  Caution dragons may live here.

Warning#

Warning

Warning dragons probably live here.

1.. warning::
2
3  Warning dragons probably live here.

Danger#

Danger

Danger dragons do live here.

1.. danger::
2
3  Danger dragons do live here.

Attention#

Attention

Look out the dragon has seen you!

1.. attention::
2
3  Look out the dragon has seen you!

Error#

Error

Ooops to late you didnt heed all the messages about dragons…

1.. error::
2
3    Ooops to late you didnt heed all the messages about dragons...

Discussion#

Please consider the display order of admonitions in the Reference section and the accompanying messages in each.

You may notice a hierarchy of colour and message urgency as you scroll down the page.

This hierarchy is a good guide for using the admonitions in your documentation and serves as a reference to maintain consistency in admonitions usage.


There are a few different ways to write admonitions. Depending on the length and style of the message, each has its merits.

For example, this works, but it looks messy in the text file.


1.. note:: Here is a line of
2    text that doesn't produce anything of interest; it just looks messy and challenging to follow in the text file where it's written.  The line width is too wide for the text editor,
3    and you need to scroll to get the message

Note

Here is a line of text that doesn’t produce anything of interest; it just looks messy and challenging to follow in the text file where it’s written. The line width is too wide for the text editor, and you need to scroll to get the message


Here are two alternative ways to layout the same .. note:: and text that improves the source text files readability and produce the same output as the first example.


1.. note::
2        Here is a line of text that doesn't produce anything of interest;
3        it just looks messy and challenging to follow in the text file
4        where it's written.  The line width is too wide for the text editor,
5        and you need to scroll to get the message

1.. note::
2
3        Here is a line of text that doesn't produce anything of interest;
4        it just looks messy and challenging to follow in the text file
5        where it's written.  The line width is too wide for the text editor,
6        and you need to scroll to get the message

Here are two short message options for a readable layout in the text editor. Both produce the same results.


1.. note:: Here is a short message.
2
3.. note::
4
5    Here is a short message.

Note

Here is a short message.


Admonition messages give you the flexibility to combine many different reST options to provide a rich statement.

See below for some demonstrated common options.

 1.. note::
 2
 3    Here is a short message with **bold** text.
 4
 5    Here is a short message *with some italic text.*
 6
 7        Here is some short text with an indentation!
 8
 9    Here is a link to :ref:`Reference <reference-admonitions>`.
10
11    Here is a link to `Google <https://google.com>`__.

Note

Here is a short message with bold text.

Here is a short message with some italic text.

Here is some short text with an indentation!

Here is a link to Reference.

Here is a link to Google.

Further Reading#


For further interesting reading on this topic, see reStructuredText directives in docutils documentation.