Add all admonitions to `directives.rst` (#12572)

Also improve documentation for the *versionchanged* directives.

doc/usage/restructuredtext/directives.rst

@@ -232,145 +232,312 @@ The ``toctree`` directive is the central element.
 Special names
 ^^^^^^^^^^^^^
 
+.. index:: pair: genindex; toctree
+           pair: modindex; toctree
+           pair: search; toctree
+
 Sphinx reserves some document names for its own use; you should not try to
 create documents with these names -- it will cause problems.
 
 The special document names (and pages generated for them) are:
 
-* ``genindex``, ``modindex``, ``search``
+* ``genindex``
 
-  These are used for the general index, the Python module index, and the search
+  This is used for the general index,
-  page, respectively.
+  which is populated with entries from :rst:dir:`index` directives
+  and all index-generating :ref:`object descriptions <basic-domain-markup>`.
+  For example, see Sphinx's :ref:`genindex`.
 
-  The general index is populated with entries from modules, all
+* ``modindex``
-  index-generating :ref:`object descriptions <basic-domain-markup>`, and from
-  :rst:dir:`index` directives.
 
-  The Python module index contains one entry per :rst:dir:`py:module`
+  This is used for the Python module index,
-  directive.
+  which contains one entry per :rst:dir:`py:module` directive.
+  For example, see Sphinx's :ref:`py-modindex`.
 
-  The search page contains a form that uses the generated JSON search index and
+* ``search``
-  JavaScript to full-text search the generated documents for search words; it
-  should work on every major browser that supports modern JavaScript.
 
-* every name beginning with ``_``
+  This is used for the search page,
+  which contains a form that uses the generated JSON search index and JavaScript
+  to full-text search the generated documents for search words;
+  it works on every major browser.
+  For example, see Sphinx's :ref:`search`.
 
-  Though few such names are currently used by Sphinx, you should not
+* Every name beginning with ``_``
-  create documents or document-containing directories with such names.  (Using
+
-  ``_`` as a prefix for a custom template directory is fine.)
+  Though few such names are currently used by Sphinx,
+  you should not create documents or document-containing directories with such names.
+  (Using ``_`` as a prefix for a custom template directory is fine.)
 
 .. warning::
 
-   Be careful with unusual characters in filenames.  Some formats may interpret
+   Be careful with unusual characters in filenames.
-   these characters in unexpected ways:
+   Some formats may interpret these characters in unexpected ways:
 
-   * Do not use the colon ``:`` for HTML based formats.  Links to other parts
+   * Do not use the colon ``:`` for HTML based formats.
-     may not work.
+     Links to other parts may not work.
-
+   * Do not use the plus ``+`` for the ePub format.
-   * Do not use the plus ``+`` for the ePub format.  Some resources may not be
+     Some resources may not be found.
-     found.
 
 
 Paragraph-level markup
 ----------------------
 
-.. index:: note, warning
-           pair: changes; in version
-
 These directives create short paragraphs and can be used inside information
 units as well as normal text.
 
+
+Admonitions, messages, and warnings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: admonition, admonitions
+           pair: attention; admonition
+           pair: caution; admonition
+           pair: danger; admonition
+           pair: error; admonition
+           pair: hint; admonition
+           pair: important; admonition
+           pair: note; admonition
+           pair: tip; admonition
+           pair: warning; admonition
+
+The admonition directives create 'admonition' elements,
+a standardised system of communicating different types of information,
+from a helpful :rst:dir:`tip` to matters of paramount :rst:dir:`danger`.
+These directives can be used anywhere an ordinary body element can,
+and can contain arbitrary body elements.
+There are nine specific named admonitions
+and the generic :rst:dir:`admonition` directive.
+
+.. rst:directive:: .. attention::
+
+   Information that requires the reader's attention.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. attention::
+
+      Please may I have your attention.
+
+.. rst:directive:: .. caution::
+
+   Information with regard to which the reader should exercise care.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. caution::
+
+      Exercise due caution.
+
+.. rst:directive:: .. danger::
+
+   Information which may lead to near and present danger if not heeded.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. danger::
+
+      Let none think to fly the danger for soon or late love is his own avenger.
+
+.. rst:directive:: .. error::
+
+   Information relating to failure modes of some description.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. error::
+
+      ERROR 418: I'm a teapot.
+
+.. rst:directive:: .. hint::
+
+   Information that is helpful to the reader.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. hint::
+
+      Look under the flowerpot.
+
+.. rst:directive:: .. important::
+
+   Information that is of paramount importance
+   and which the reader must not ignore.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. important::
+
+      This is a statement of paramount importance.
+
 .. rst:directive:: .. note::
 
-   An especially important bit of information about an API that a user should be
+   An especially important bit of information that the reader should know.
-   aware of when using whatever bit of API the note pertains to.  The content of
+   The content of the directive should be written in complete sentences
-   the directive should be written in complete sentences and include all
+   and include all appropriate punctuation.
-   appropriate punctuation.
 
-   Example::
+   Example:
 
    .. note::
 
-         This function is not suitable for sending spam e-mails.
+      This function is not suitable for sending tins of spam.
+
+.. rst:directive:: .. tip::
+
+   Some useful tidbit of information for the reader.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
+
+   Example:
+
+   .. tip::
+
+      Remember your sun cream!
 
 .. rst:directive:: .. warning::
 
-   An important bit of information about an API that a user should be very aware
+   An important bit of information that the reader should be very aware of.
-   of when using whatever bit of API the warning pertains to.  The content of
+   The content of the directive should be written in complete sentences
-   the directive should be written in complete sentences and include all
+   and include all appropriate punctuation.
-   appropriate punctuation. This differs from :rst:dir:`note` in that it is
-   recommended over :rst:dir:`note` for information regarding security.
 
-.. rst:directive:: .. versionadded:: version
+   Example:
 
-   This directive documents the version of the project which added the described
+   .. warning::
-   feature to the library or C API. When this applies to an entire module, it
-   should be placed at the top of the module section before any prose.
 
-   The first argument must be given and is the version in question; you can add
+      Beware of the dog.
-   a second argument consisting of a *brief* explanation of the change.
 
-   Example::
+.. rst:directive:: .. admonition:: title
 
-      .. versionadded:: 2.5
+   A generic admonition, with an optional title.
-         The *spam* parameter.
+   The content of the directive should be written in complete sentences
+   and include all appropriate punctuation.
 
-   Note that there must be no blank line between the directive head and the
+   Example:
-   explanation; this is to make these blocks visually continuous in the markup.
 
-.. rst:directive:: .. versionchanged:: version
+   .. admonition:: This is a title
 
-   Similar to :rst:dir:`versionadded`, but describes when and what changed in
+      This is the content of the admonition.
-   the named feature in some way (new parameters, changed side effects, etc.).
 
-.. rst:directive:: .. deprecated:: version
-
-   Similar to :rst:dir:`versionchanged`, but describes when the feature was
-   deprecated.  An explanation can also be given, for example to inform the
-   reader what should be used instead.  Example::
-
-      .. deprecated:: 3.1
-         Use :func:`spam` instead.
-
-.. rst:directive:: .. versionremoved:: version
-
-   Similar to :rst:dir:`versionadded`, but describes when the feature was removed.
-   An explanation may be provided to inform the reader what to use instead,
-   or why the feature was removed.
-   Example::
-
-      .. versionremoved:: 4.0
-         The :func:`spam` function is more flexible, and should be used instead.
-
-   .. versionadded:: 7.3
 
 .. rst:directive:: seealso
 
    Many sections include a list of references to module documentation or
-   external documents.  These lists are created using the :rst:dir:`seealso`
+   external documents.
-   directive.
+   These lists are created using the :rst:dir:`seealso` directive.
 
-   The :rst:dir:`seealso` directive is typically placed in a section just before
+   The :rst:dir:`!seealso` directive is typically placed in a section
-   any subsections.  For the HTML output, it is shown boxed off from the main
+   just before any subsections.
-   flow of the text.
+   The content of the :rst:dir:`seealso` directive should be
+   either a single line or a reStructuredText `definition list`_.
 
-   The content of the :rst:dir:`seealso` directive should be a reStructuredText definition
+   .. _definition list: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists
-   list. Example::
+
+   Example::
+
+      .. seealso::
+
+         Python's :py:mod:`zipfile` module
+            Documentation of Python's standard :py:mod:`zipfile` module.
+
+         `GNU tar manual, Basic Tar Format <https://example.org>`_
+            Documentation for tar archive files, including GNU tar extensions.
 
    .. seealso::
 
       Module :py:mod:`zipfile`
          Documentation of the :py:mod:`zipfile` standard module.
 
-         `GNU tar manual, Basic Tar Format <https://link>`_
+      `GNU tar manual, Basic Tar Format <https://example.org>`_
          Documentation for tar archive files, including GNU tar extensions.
 
-   There's also a "short form" allowed that looks like this::
 
-      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
+Describing changes between versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   .. versionadded:: 0.5
+.. index:: pair: added; in version
-      The short form.
+           pair: changes; in version
+           pair: removed; in version
+
+.. rst:directive:: .. versionadded:: version [brief explanation]
+
+   This directive documents the version of the project
+   which added the described feature.
+   When this applies to an entire module or component,
+   it should be placed at the top of the relevant section before any prose.
+
+   The first argument must be given and is the version in question; you can add
+   a second argument consisting of a *brief* explanation of the change.
+
+   .. attention::
+      There must be no blank line between the directive head and the explanation;
+      this is to make these blocks visually continuous in the markup.
+
+   Example::
+
+      .. versionadded:: 2.5
+         The *spam* parameter.
+
+   .. versionadded:: 2.5
+      The *spam* parameter.
+
+.. rst:directive:: .. versionchanged:: version [brief explanation]
+
+   Similar to :rst:dir:`versionadded`, but describes when and what changed in
+   the named feature in some way (new parameters, changed side effects, etc.).
+
+   Example::
+
+      .. versionchanged:: 2.8
+         The *spam* parameter is now of type *boson*.
+
+   .. versionchanged:: 2.8
+      The *spam* parameter is now of type *boson*.
+
+.. rst:directive:: .. deprecated:: version [brief explanation]
+
+   Similar to :rst:dir:`versionadded`, but describes when the feature was
+   deprecated.
+   A *brief* explanation can also be given,
+   for example to tell the reader what to use instead.
+
+   Example::
+
+      .. deprecated:: 3.1
+         Use :py:func:`spam` instead.
+
+   .. deprecated:: 3.1
+      Use :py:func:`!spam` instead.
+
+.. rst:directive:: .. versionremoved:: version [brief explanation]
+
+   Similar to :rst:dir:`versionadded`, but describes when the feature was removed.
+   An explanation may be provided to tell the reader what to use instead,
+   or why the feature was removed.
+
+   .. versionadded:: 7.3
+
+   Example::
+
+      .. versionremoved:: 4.0
+         The :py:func:`spam` function is more flexible, and should be used instead.
+
+   .. versionremoved:: 4.0
+      The :py:func:`!spam` function is more flexible, and should be used instead.
+
+
+Presentational
+^^^^^^^^^^^^^^
 
 .. rst:directive:: .. rubric:: title
 
@@ -396,10 +563,7 @@ units as well as normal text.
 
 .. rst:directive:: centered
 
-   This directive creates a centered boldfaced line of text.  Use it as
+   This directive creates a centered boldfaced line of text.
-   follows::
-
-      .. centered:: LICENSE AGREEMENT
 
    .. deprecated:: 1.1
       This presentation-only directive is a legacy from older versions.

sphinx/domains/changeset.py

@@ -110,7 +110,7 @@ class ChangeSetDomain(Domain):
     name = 'changeset'
     label = 'changeset'
 
-    initial_data: dict[str, Any] = {
+    initial_data: dict[str, dict[str, list[ChangeSet]]] = {
         'changes': {},      # version -> list of ChangeSet
     }