mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Add all admonitions to `directives.rst` (#12572)
Also improve documentation for the *versionchanged* directives.
This commit is contained in:
Adam Turner
GitHub
parent
0f38c9c15d
commit
3456ff3ca3
@ -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
|
||||
page, respectively.
|
||||
This is used for the general index,
|
||||
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
|
||||
index-generating :ref:`object descriptions <basic-domain-markup>`, and from
|
||||
:rst:dir:`index` directives.
|
||||
* ``modindex``
|
||||
|
||||
The Python module index contains one entry per :rst:dir:`py:module`
|
||||
directive.
|
||||
This is used for the Python module index,
|
||||
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
|
||||
JavaScript to full-text search the generated documents for search words; it
|
||||
should work on every major browser that supports modern JavaScript.
|
||||
* ``search``
|
||||
|
||||
* 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
|
||||
create documents or document-containing directories with such names. (Using
|
||||
``_`` as a prefix for a custom template directory is fine.)
|
||||
* Every name beginning with ``_``
|
||||
|
||||
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
|
||||
these characters in unexpected ways:
|
||||
Be careful with unusual characters in filenames.
|
||||
Some formats may interpret these characters in unexpected ways:
|
||||
|
||||
* Do not use the colon ``:`` for HTML based formats. Links to other parts
|
||||
may not work.
|
||||
|
||||
* Do not use the plus ``+`` for the ePub format. Some resources may not be
|
||||
found.
|
||||
* Do not use the colon ``:`` for HTML based formats.
|
||||
Links to other parts may not work.
|
||||
* Do not use the plus ``+`` for the ePub format.
|
||||
Some resources may not be 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
|
||||
aware of when using whatever bit of API the note pertains to. The content of
|
||||
the directive should be written in complete sentences and include all
|
||||
appropriate punctuation.
|
||||
An especially important bit of information that the reader should know.
|
||||
The content of the directive should be written in complete sentences
|
||||
and include all appropriate punctuation.
|
||||
|
||||
Example::
|
||||
Example:
|
||||
|
||||
.. note::
|
||||
.. 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
|
||||
of when using whatever bit of API the warning pertains to. The content of
|
||||
the directive should be written in complete sentences and include all
|
||||
appropriate punctuation. This differs from :rst:dir:`note` in that it is
|
||||
recommended over :rst:dir:`note` for information regarding security.
|
||||
An important bit of information that the reader should be very aware of.
|
||||
The content of the directive should be written in complete sentences
|
||||
and include all appropriate punctuation.
|
||||
|
||||
.. rst:directive:: .. versionadded:: version
|
||||
Example:
|
||||
|
||||
This directive documents the version of the project which added the described
|
||||
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.
|
||||
.. warning::
|
||||
|
||||
Beware of the dog.
|
||||
|
||||
.. rst:directive:: .. admonition:: title
|
||||
|
||||
A generic admonition, with an optional title.
|
||||
The content of the directive should be written in complete sentences
|
||||
and include all appropriate punctuation.
|
||||
|
||||
Example:
|
||||
|
||||
.. admonition:: This is a title
|
||||
|
||||
This is the content of the admonition.
|
||||
|
||||
|
||||
.. 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` directive.
|
||||
|
||||
The :rst:dir:`!seealso` directive is typically placed in a section
|
||||
just before any subsections.
|
||||
The content of the :rst:dir:`seealso` directive should be
|
||||
either a single line or a reStructuredText `definition list`_.
|
||||
|
||||
.. _definition list: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists
|
||||
|
||||
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://example.org>`_
|
||||
Documentation for tar archive files, including GNU tar extensions.
|
||||
|
||||
|
||||
Describing changes between versions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. index:: pair: added; in version
|
||||
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.
|
||||
|
||||
Note that there must be no blank line between the directive head and the
|
||||
explanation; this is to make these blocks visually continuous in the markup.
|
||||
.. versionadded:: 2.5
|
||||
The *spam* parameter.
|
||||
|
||||
.. rst:directive:: .. versionchanged:: version
|
||||
.. 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.).
|
||||
|
||||
.. 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.
|
||||
.. 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
|
||||
|
||||
.. rst:directive:: seealso
|
||||
Example::
|
||||
|
||||
Many sections include a list of references to module documentation or
|
||||
external documents. These lists are created using the :rst:dir:`seealso`
|
||||
directive.
|
||||
.. versionremoved:: 4.0
|
||||
The :py:func:`spam` function is more flexible, and should be used instead.
|
||||
|
||||
The :rst:dir:`seealso` directive is typically placed in a section just before
|
||||
any subsections. For the HTML output, it is shown boxed off from the main
|
||||
flow of the text.
|
||||
.. versionremoved:: 4.0
|
||||
The :py:func:`!spam` function is more flexible, and should be used instead.
|
||||
|
||||
The content of the :rst:dir:`seealso` directive should be a reStructuredText definition
|
||||
list. Example::
|
||||
|
||||
.. seealso::
|
||||
|
||||
Module :py:mod:`zipfile`
|
||||
Documentation of the :py:mod:`zipfile` standard module.
|
||||
|
||||
`GNU tar manual, Basic Tar Format <https://link>`_
|
||||
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`
|
||||
|
||||
.. versionadded:: 0.5
|
||||
The short form.
|
||||
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
|
||||
follows::
|
||||
|
||||
.. centered:: LICENSE AGREEMENT
|
||||
This directive creates a centered boldfaced line of text.
|
||||
|
||||
.. deprecated:: 1.1
|
||||
This presentation-only directive is a legacy from older versions.
|
||||
|
||||
@ -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
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user