Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Add anchors to markup.rst #1559

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Add anchors to markup.rst #1559

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3fb9630
Add anchors
StanFromIreland May 9, 2025
f601de7
Use glossary
StanFromIreland May 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 113 additions & 105 deletions 218 documentation/markup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<style> .green {color:#008000; font-weight:bold; font-size:16px} </style>

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 <information-units>`
(``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 <information-units>`
(``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 <http://link>`_
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 <http://link>`_
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
Expand Down
Morty Proxy This is a proxified and sanitized view of the page, visit original site.