diff --git a/documentation/markup.rst b/documentation/markup.rst index 65b8b8d03..241968d42 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -1050,170 +1050,178 @@ Paragraph-level markup These directives create short paragraphs and can be used inside information units as well as normal text: -.. describe:: note +.. raw:: html - 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. + - Example:: +.. role:: green - .. note:: +.. glossary:: - This function is not suitable for sending spam e-mails. + :green:`note` -.. describe:: warning + 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 important bit of information about an API that a user should be 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. In the interest of not scaring users away from pages filled - with warnings, this directive should only be chosen over ``note`` for - information regarding the possibility of crashes, data loss, or security - implications. + Example:: -.. describe:: versionadded + .. note:: - This directive documents the version of Python which added the described - feature, or a part of it, 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. - When adding a new API :ref:`with a directive ` - (``class``, ``attribute``, ``function``, ``method``, ``c:type``, etc), - a ``versionadded`` should be included at the end of its description block. + This function is not suitable for sending spam e-mails. - The first argument must be given and is the version in question. - Instead of a specific version number, you can---and should---use - the word ``next``, indicating that the API will first appear in the - upcoming release. - The second argument is optional and can be used to describe the details of the feature. + :green:`warning` - Example:: + An important bit of information about an API that a user should be 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. In the interest of not scaring users away from pages filled + with warnings, this directive should only be chosen over ``note`` for + information regarding the possibility of crashes, data loss, or security + implications. - .. function:: func() + :green:`versionadded` - Return foo and bar. + This directive documents the version of Python which added the described + feature, or a part of it, 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. + When adding a new API :ref:`with a directive ` + (``class``, ``attribute``, ``function``, ``method``, ``c:type``, etc), + a ``versionadded`` should be included at the end of its description block. - .. versionadded:: next + The first argument must be given and is the version in question. + Instead of a specific version number, you can---and should---use + the word ``next``, indicating that the API will first appear in the + upcoming release. + The second argument is optional and can be used to describe the details of the feature. - When a release is made, the release manager will change the ``next`` to - the just-released version. For example, if ``func`` in the above example is - released in 3.14, the snippet will be changed to:: + Example:: - .. function:: func() + .. function:: func() - Return foo and bar. + Return foo and bar. - .. versionadded:: 3.14 + .. versionadded:: next - The tool to do this replacement is `update_version_next.py`_ - in the release-tools repository. + When a release is made, the release manager will change the ``next`` to + the just-released version. For example, if ``func`` in the above example is + released in 3.14, the snippet will be changed to:: - .. _update_version_next.py: https://github.com/python/release-tools/blob/master/update_version_next.py + .. function:: func() - When backporting to versions before 3.14, check if ``Doc/tools/extensions/pyspecific.py`` - contains the function ``expand_version_arg``. If it's not there, - use a specific version instead of ``next``. + Return foo and bar. - When adding documentation for a function that existed in a past version, - but wasn't documented yet, use the version number where the function was - added instead of ``next``. + .. versionadded:: 3.14 -.. describe:: versionchanged + The tool to do this replacement is `update_version_next.py`_ + in the release-tools repository. - Similar to ``versionadded``, but describes when and what changed in the named - feature in some way (new parameters, changed side effects, platform support, - etc.). This one *must* have the second argument (explanation of the change). + .. _update_version_next.py: https://github.com/python/release-tools/blob/master/update_version_next.py - Example:: + When backporting to versions before 3.14, check if ``Doc/tools/extensions/pyspecific.py`` + contains the function ``expand_version_arg``. If it's not there, + use a specific version instead of ``next``. - .. function:: func(spam=False) + When adding documentation for a function that existed in a past version, + but wasn't documented yet, use the version number where the function was + added instead of ``next``. - Return foo and bar, optionally with *spam* applied. + :green:`versionchanged` - .. versionchanged:: next - Added the *spam* parameter. + Similar to ``versionadded``, but describes when and what changed in the named + feature in some way (new parameters, changed side effects, platform support, + etc.). This one *must* have the second argument (explanation of the change). - Note that there should be no blank line between the directive head and the - explanation; this is to make these blocks visually continuous in the markup. + Example:: -.. describe:: deprecated + .. function:: func(spam=False) - Indicates the version from which the described feature is deprecated. + Return foo and bar, optionally with *spam* applied. - There is one required argument: the version from which the feature is - deprecated. - Similarly to ``versionadded``, you should use the word ``next`` to indicate - the API will be first deprecated in the upcoming release. + .. versionchanged:: next + Added the *spam* parameter. - Example:: + Note that there should be no blank line between the directive head and the + explanation; this is to make these blocks visually continuous in the markup. - .. deprecated:: next + :green:`deprecated` -.. describe:: deprecated-removed + Indicates the version from which the described feature is deprecated. - Like ``deprecated``, but it also indicates in which version the feature is - removed. + There is one required argument: the version from which the feature is + deprecated. + Similarly to ``versionadded``, you should use the word ``next`` to indicate + the API will be first deprecated in the upcoming release. - There are two required arguments: the version from which the feature is - deprecated (usually ``next``), and the version in which the feature - is removed, which must be a specific version number (*not* ``next``). + Example:: - Example:: + .. deprecated:: next - .. deprecated-removed:: next 4.0 + :green:`deprecated-removed` -.. describe:: impl-detail + Like ``deprecated``, but it also indicates in which version the feature is + removed. - This directive is used to mark CPython-specific information. Use either with - a block content or a single sentence as an argument, that is, either :: + There are two required arguments: the version from which the feature is + deprecated (usually ``next``), and the version in which the feature + is removed, which must be a specific version number (*not* ``next``). - .. impl-detail:: + Example:: - This describes some implementation detail. + .. deprecated-removed:: next 4.0 - More explanation. + :green:`impl-detail` - or :: + This directive is used to mark CPython-specific information. Use either with + a block content or a single sentence as an argument, that is, either :: - .. impl-detail:: This shortly mentions an implementation detail. + .. impl-detail:: - "\ **CPython implementation detail:**\ " is automatically prepended to the - content. + This describes some implementation detail. -.. describe:: seealso + More explanation. - Many sections include a list of references to module documentation or - external documents. These lists are created using the ``seealso`` directive. + or :: - The ``seealso`` directive is typically placed in a section just before any - sub-sections. For the HTML output, it is shown boxed off from the main flow - of the text. + .. impl-detail:: This shortly mentions an implementation detail. - The content of the ``seealso`` directive should be a reST definition list. - Example:: + "\ **CPython implementation detail:**\ " is automatically prepended to the + content. - .. seealso:: + :green:`seealso` - Module :mod:`zipfile` - Documentation of the :mod:`zipfile` standard module. + Many sections include a list of references to module documentation or + external documents. These lists are created using the ``seealso`` directive. - `GNU tar manual, Basic Tar Format `_ - Documentation for tar archive files, including GNU tar extensions. + The ``seealso`` directive is typically placed in a section just before any + sub-sections. For the HTML output, it is shown boxed off from the main flow + of the text. -.. describe:: rubric + The content of the ``seealso`` directive should be a reST definition list. + Example:: - This directive creates a paragraph heading that is not used to create a - table of contents node. It is currently used for the "Footnotes" caption. + .. seealso:: -.. describe:: centered + Module :mod:`zipfile` + Documentation of the :mod:`zipfile` standard module. - This directive creates a centered boldfaced paragraph. Use it as follows:: + `GNU tar manual, Basic Tar Format `_ + Documentation for tar archive files, including GNU tar extensions. - .. centered:: + :green:`rubric` - Paragraph contents. + This directive creates a paragraph heading that is not used to create a + table of contents node. It is currently used for the "Footnotes" caption. + + :green:`centered` + + This directive creates a centered boldfaced paragraph. Use it as follows:: + + .. centered:: + + Paragraph contents. Table-of-contents markup