diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 72df2d5d391..69931d13f88 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/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 - 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 `. + For example, see Sphinx's :ref:`genindex`. - The general index is populated with entries from modules, all - index-generating :ref:`object descriptions `, 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 ``_`` -.. warning:: + 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.) - Be careful with unusual characters in filenames. Some formats may interpret - these characters in unexpected ways: +.. warning:: - * Do not use the colon ``:`` for HTML based formats. Links to other parts - may not work. + Be careful with unusual characters in filenames. + Some formats may interpret these characters in unexpected ways: - * 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:: + + This function is not suitable for sending tins of spam. - .. note:: +.. rst:directive:: .. tip:: - This function is not suitable for sending spam e-mails. + 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. + + Example: + + .. warning:: -.. rst:directive:: .. versionadded:: version + Beware of the dog. - 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. +.. 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 `_ + 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 `_ + 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:: + Example:: - .. deprecated:: 3.1 - Use :func:`spam` instead. + .. versionchanged:: 2.8 + The *spam* parameter is now of type *boson*. -.. rst:directive:: .. versionremoved:: version + .. versionchanged:: 2.8 + The *spam* parameter is now of type *boson*. - 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:: +.. rst:directive:: .. deprecated:: version [brief explanation] - .. versionremoved:: 4.0 - The :func:`spam` function is more flexible, and should be used instead. + 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. - .. versionadded:: 7.3 + Example:: -.. rst:directive:: seealso + .. deprecated:: 3.1 + Use :py:func:`spam` instead. - Many sections include a list of references to module documentation or - external documents. These lists are created using the :rst:dir:`seealso` - directive. + .. deprecated:: 3.1 + Use :py:func:`!spam` 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. +.. rst:directive:: .. versionremoved:: version [brief explanation] - The content of the :rst:dir:`seealso` directive should be a reStructuredText definition - list. Example:: + 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. - .. seealso:: + .. versionadded:: 7.3 - Module :py:mod:`zipfile` - Documentation of the :py:mod:`zipfile` standard module. + Example:: - `GNU tar manual, Basic Tar Format `_ - Documentation for tar archive files, including GNU tar extensions. + .. versionremoved:: 4.0 + The :py:func:`spam` function is more flexible, and should be used instead. - There's also a "short form" allowed that looks like this:: + .. versionremoved:: 4.0 + The :py:func:`!spam` function is more flexible, and should be used instead. - .. 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. diff --git a/sphinx/domains/changeset.py b/sphinx/domains/changeset.py index 762785d3160..cc1d4a33824 100644 --- a/sphinx/domains/changeset.py +++ b/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 }