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.