Admonitions#

Admonitions are a great way to bring the attention of readers. It is a special kind of directives. There are many different types of admonitions, including the reStructuredText’s built-in admonitions, and directives provided by Sphinx which looks like admonitions.

reST admonitions#

Here lists all the built-in admonitions in reST. The admonition syntax in reST accepts no arguments, and most of the time no options:

.. admonition-name::
   content in admonition

Here is an example of the note admonition:

note#
.. note::
   ``note`` is a special directive for admonition.

Note

note is a special directive for admonition.

attention#

Attention

Shibuya is a well designed Sphinx theme.

caution#

Caution

Livereload is using tornado for the server.

danger#

Danger

A non-sustainable project is no trustworthy to use.

error#

Error

One can not be divided by zero.

hint#

Hint

Authlib helps you build an OpenID Connect server.

important#

Important

I sometimes write blog posts on https://lepture.com

note#

Note

Typlog is created by me.

tip#

Tip

Become a sponsor to keep this project sustainable.

warning#

Warning

Do not ask your own questions in GitHub issues.

Generic admonition#

A generic .. admonition:: directive accepts a custom title:

.. admonition:: Admonition title here

   Content of the admonition

Here is an example of the generic admonition:

generic admonition#
.. admonition:: Typlog

   Typlog can help you hosting your blogs and podcasts.

Typlog

Typlog can help you hosting your blogs and podcasts.

By default, a generic admonition is decorated with your theme color. But you can customize the result with a :class: option. With the above admonitions as the class name, the result would look like the above admonitions:

custom admonition#
.. admonition:: Typlog
   :class: hint

   Typlog can help you hosting your blogs and podcasts.

Typlog

Typlog can help you hosting your blogs and podcasts.

Admonition-like directives#

Here lists the directives added by Sphinx which looks like admonitions.

seealso#

See also

The blog post about Shibuya by lepture.

todo#

The todo admonition is enabled by sphinx.ext.todo, please add this extension in the conf.py file.

conf.py#
extensions = [
    "sphinx.ext.todo",
]
todo_include_todos = True

Todo

Fix this UI issue later.

Versions directives#

Here lists the version related directives. These directives are not admonitions, but in Shibuya theme, they look like admonitions.

versionadded#

versionadded#
.. versionadded:: v3
   Built-in reST renderer is added in Mistune.

Added in version v3: Built-in reST renderer is added in Mistune.

versionchanged#

versionchanged#
.. versionchanged:: v2
   The ``jose`` module is moved out of Authlib.

Changed in version v2: The jose module is moved out of Authlib.

versionremoved#

versionremoved#
.. versionremoved:: 4.0
    The :py:func:`spam` function is more flexible, and should be used instead.

Removed in version 4.0: The spam() function is more flexible, and should be used instead.

deprecated#

deprecated#
.. deprecated:: 2.7
   This version is no longer maintained, please upgrade to v3.

Deprecated since version 2.7: This version is no longer maintained, please upgrade to v3.

Nesting admonitions#

It is possible to add admonitions into admonitions. Take an example:

.. note::

   An admonition can contain another admonition.

   .. warning::

      But is is not a really good idea.

      .. danger::

         It's distracting.

     It can also be confusing.

     - It can contain list.

   And it looks pretty weird.

Note

An admonition can contain another admonition.

Warning

But is is not a really good idea.

Danger

It’s distracting.

It can also be confusing.

  • It can contain list.

And it looks pretty weird.