===========
Admonitions
===========

These are coloured boxed useful to highlight information.

List of admonitions
===================

``admonition``
--------------

.. admonition:: Example

   This is an admonition block named example. You can choose the title.

``attention``
-------------

.. attention::

   This is an attention block.

``caution``
-----------

.. caution::

   This is a caution block.

``danger``
----------

.. danger::
   
   This is a danger block.

``error``
---------

.. error::

   This is an error block.

``hint``
--------

.. hint::

   This is a hint block.
   
``important``
-------------

.. important::

   This is an important block.

``note``
--------

.. note::

   This is a note block.

``seealso``
-----------

.. seealso::

   This is a seealso block.

``tip``
-------

.. tip::

   This is a tip block.

``todo``
--------

.. todo::

   This is a todo block. It needs the ``sphinx.ext.todo`` extension.

``todo`` blocks can be useful to track missing things. They can be swithced off in ``conf.py`` with

.. code-block:: python

   todo_include_todos = False

So if you don't see the ``todo`` above, this is why.

``warning``
-----------

.. warning::
   
   This is a warning block.

Describing changes between versions
===================================

The following admonition blocks are useful to highlight changes between versions of Yambo, for example if a feature is added or the name of an input variable is changed.

.. versionadded:: 5.0
   Brief explanation.

.. versionchanged:: 5.0
   Brief explanation.

.. deprecated:: 5.0
   Brief explanation.

.. versionremoved:: 5.0
   Brief explanation.

Place this directives just before the related/affected content. 

.. note::

   In version ``8.3`` of ``sphinx`` the names of these directives have been changed to
   ``version-added``, ``version-changed``, ``version-deprecated``, ``version-removed``.
   See `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions>`__.

Collapsible option
==================

From version 8.2 of ``sphinx`` each admonition directive supports a ``:collapsible:`` option. See `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directives>`_.

.. note::
   :collapsible:

   Collapsible directives look a bit ugly tho (at least with Furo...)

Even if ``:collapsible:`` is the default way to do this, the ``sphinx-togglebutton`` extension (`documentation here <https://sphinx-togglebutton.readthedocs.io/en/latest/index.html#>`__) allows to add ``:class: dropdown`` to the ``admonition``:

.. caution::
   :class: dropdown, toggle-shown

   This looks way better, but it also requires ``sphinx-design``!

A different way to collapse text is provided by :ref:`dropdowns <ref-sphinx-design-dropdown>`.

rST vs MD syntax
================

.. tab-set::

    .. tab-item:: rST

        .. literalinclude:: example_files/RSTsyntax_admonition.rst

    .. tab-item:: MD

        .. literalinclude:: example_files/MDsyntax_admonition.md