Skip to content

Use hyphenated version directives #13714

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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Use hyphenated version directives #13714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
deb736f
Hyphenate versioning admonitions
stephenfin Jul 2, 2025
6e01dbf
docs: Use hyphenated versioning admonitions
stephenfin Jul 3, 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
2 changes: 1 addition & 1 deletion doc/development/howtos/builders.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Configuring builders
Discover builders by entry point
--------------------------------

.. versionadded:: 1.6
.. version-added:: 1.6

:term:`builder` extensions can be discovered by means of `entry points`_ so
that they do not have to be listed in the :confval:`extensions` configuration
Expand Down
20 changes: 10 additions & 10 deletions doc/development/html_themes/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
HTML theme development
======================

.. versionadded:: 0.6
.. version-added:: 0.6

.. note::

Expand Down Expand Up @@ -82,7 +82,7 @@ and the corresponding default value.
These options can be overridden by the user in :confval:`html_theme_options`
and are accessible from all templates as ``theme_<name>``.

.. versionadded:: 7.3
.. version-added:: 7.3
``theme.toml`` support.

.. _TOML: https://toml.io/en/
Expand Down Expand Up @@ -155,10 +155,10 @@ Python :mod:`configparser` module) and has the following structure:
These options can be overridden by the user in :confval:`html_theme_options`
and are accessible from all templates as ``theme_<name>``.

.. versionadded:: 1.7
.. version-added:: 1.7
sidebar settings

.. versionchanged:: 5.1
.. version-changed:: 5.1

The stylesheet setting accepts multiple CSS filenames

Expand All @@ -178,7 +178,7 @@ The required argument is a path to a directory containing a ``theme.conf`` file.
The programme will write a ``theme.toml`` file in the same directory,
and will not modify the original ``theme.conf`` file.

.. versionadded:: 7.3
.. version-added:: 7.3

.. _distribute-your-theme:

Expand Down Expand Up @@ -211,13 +211,13 @@ using the :meth:`~sphinx.application.Sphinx.add_html_theme` API:
If your theme package contains two or more themes, please call
``add_html_theme()`` twice or more.

.. versionadded:: 1.2
.. version-added:: 1.2
'sphinx_themes' entry_points feature.

.. deprecated:: 1.6
.. version-changed:: 1.6
``sphinx_themes`` entry_points has been deprecated.

.. versionadded:: 1.6
.. version-added:: 1.6
``sphinx.html_themes`` entry_points feature.


Expand All @@ -236,7 +236,7 @@ The :confval:`!stylesheets` setting can be used to add custom CSS files to a the
Styling search result entries by category
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 8.0
.. version-added:: 8.0

.. note::

Expand Down Expand Up @@ -330,7 +330,7 @@ When a documentation project is built with that theme,
the output directory will contain a ``_static/theme_styles.css`` file
where all template tags have been processed.

.. versionchanged:: 7.4
.. version-changed:: 7.4

The preferred suffix for static templates is now ``.jinja``, in line with
the Jinja project's `recommended file extension`_.
Expand Down
22 changes: 11 additions & 11 deletions doc/development/html_themes/templating.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,24 +188,24 @@ is deprecated in favor of separate sidebar templates, which can be included via
``sidebartoc``
The table of contents within the sidebar.

.. deprecated:: 1.0
.. version-deprecated:: 1.0

``sidebarrel``
The relation links (previous, next document) within the sidebar.

.. deprecated:: 1.0
.. version-deprecated:: 1.0

``sidebarsourcelink``
The "Show source" link within the sidebar (normally only shown if this is
enabled by :confval:`html_show_sourcelink`).

.. deprecated:: 1.0
.. version-deprecated:: 1.0

``sidebarsearch``
The search box within the sidebar. Override this if you want to place some
content at the bottom of the sidebar.

.. deprecated:: 1.0
.. version-deprecated:: 1.0


Configuration Variables
Expand Down Expand Up @@ -237,7 +237,7 @@ Overriding works like this::

{% set script_files = script_files + ["_static/myscript.js"] %}

.. deprecated:: 1.8.0
.. version-deprecated:: 1.8.0

Please use ``.Sphinx.add_js_file()`` instead.

Expand Down Expand Up @@ -305,7 +305,7 @@ in the future.
The relative path to the HTML favicon image from the current document, or
URL to the favicon, or ``''``.

.. versionadded:: 4.0
.. version-added:: 4.0

.. data:: file_suffix

Expand All @@ -331,15 +331,15 @@ in the future.
The relative path to the HTML logo image from the current document, or URL
to the logo, or ``''``.

.. versionadded:: 4.0
.. version-added:: 4.0

.. data:: master_doc
root_doc

The value of :confval:`master_doc` or :confval:`root_doc` (aliases),
for usage with :func:`pathto`.

.. versionadded:: 4.0
.. version-added:: 4.0
The :data:`!root_doc` template variable.

.. data:: pagename
Expand Down Expand Up @@ -383,7 +383,7 @@ in the future.
The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``.
``final`` always has 0 as the last element.

.. versionadded:: 4.2
.. version-added:: 4.2

.. data:: docutils_version_info

Expand All @@ -392,14 +392,14 @@ in the future.
The fourth element can be one of: ``alpha``, ``beta``, ``candidate``, ``final``.
``final`` always has 0 as the last element.

.. versionadded:: 5.0.2
.. version-added:: 5.0.2

.. data:: styles

A list of the names of the main stylesheets as given by the theme or
:confval:`html_style`.

.. versionadded:: 5.1
.. version-added:: 5.1

.. data:: title

Expand Down
38 changes: 19 additions & 19 deletions doc/extdev/event_callbacks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Here is a more detailed list of these events.

Emitted when the config object has been initialized.

.. versionadded:: 1.8
.. version-added:: 1.8

.. event:: builder-inited (app)

Expand All @@ -118,7 +118,7 @@ Here is a more detailed list of these events.
that the environment has determined.
You can return a list of docnames to re-read in addition to these.

.. versionadded:: 1.1
.. version-added:: 1.1

.. event:: env-purge-doc (app, env, docname)

Expand All @@ -135,7 +135,7 @@ Here is a more detailed list of these events.
When a source file has been changed, the cache's entries for the file are cleared,
since the module declarations could have been removed from the file.

.. versionadded:: 0.5
.. version-added:: 0.5

.. event:: env-before-read-docs (app, env, docnames)

Expand All @@ -153,7 +153,7 @@ Here is a more detailed list of these events.
You can also remove document names; do this with caution since it will make
Sphinx treat changed files as unchanged.

.. versionadded:: 1.3
.. version-added:: 1.3

.. event:: source-read (app, docname, content)

Expand All @@ -172,7 +172,7 @@ Here is a more detailed list of these events.
LaTeX, you can use a regular expression to replace ``$...$`` by
``:math:`...```.

.. versionadded:: 0.5
.. version-added:: 0.5

.. event:: include-read (app, relative_path, parent_docname, content)

Expand All @@ -192,7 +192,7 @@ Here is a more detailed list of these events.
You can process the ``content`` and replace this item
to transform the included content, as with the :event:`source-read` event.

.. versionadded:: 7.2.5
.. version-added:: 7.2.5

.. seealso:: The :dudir:`include` directive and the :event:`source-read` event.

Expand All @@ -207,7 +207,7 @@ Here is a more detailed list of these events.
*objtype* arguments are strings indicating object description of the object.
And *contentnode* is a content for the object. It can be modified in-place.

.. versionadded:: 2.4
.. version-added:: 2.4

.. event:: doctree-read (app, doctree)

Expand Down Expand Up @@ -240,7 +240,7 @@ Here is a more detailed list of these events.
or raise :class:`~sphinx.errors.NoUri` to prevent other handlers in
trying and suppress a warning about this cross-reference being unresolved.

.. versionadded:: 0.5
.. version-added:: 0.5

.. event:: warn-missing-reference (app, domain, node)

Expand All @@ -257,7 +257,7 @@ Here is a more detailed list of these events.
:confval:`nitpick_ignore` and :confval:`nitpick_ignore_regex`
prevent the event from being emitted for the corresponding nodes.

.. versionadded:: 3.4
.. version-added:: 3.4

.. event:: doctree-resolved (app, doctree, docname)

Expand Down Expand Up @@ -290,7 +290,7 @@ Here is a more detailed list of these events.
environment from the main process. *docnames* is a set of document names
that have been read in the subprocess.

.. versionadded:: 1.3
.. version-added:: 1.3

.. event:: env-updated (app, env)

Expand All @@ -305,9 +305,9 @@ Here is a more detailed list of these events.
will then be considered updated, and will be (re-)written during the writing
phase.

.. versionadded:: 0.5
.. version-added:: 0.5

.. versionchanged:: 1.3
.. version-changed:: 1.3
The handlers' return value is now used.

.. event:: env-get-updated (app, env)
Expand All @@ -328,7 +328,7 @@ Here is a more detailed list of these events.
Emitted when Consistency checks phase. You can check consistency of
metadata for whole of documents.

.. versionadded:: 1.6
.. version-added:: 1.6

.. event:: write-started (app, builder)

Expand All @@ -338,7 +338,7 @@ Here is a more detailed list of these events.
Emitted before the builder starts to
resolve and write documents.

.. versionadded:: 7.4
.. version-added:: 7.4

.. event:: build-finished (app, exception)

Expand All @@ -352,7 +352,7 @@ Here is a more detailed list of these events.
raised no exception, *exception* will be ``None``. This allows to customize
cleanup actions depending on the exception status.

.. versionadded:: 0.5
.. version-added:: 0.5

Builder specific events
-----------------------
Expand All @@ -370,7 +370,7 @@ These events are emitted by specific builders.

You can add pages to write by returning an iterable from this event.

.. versionadded:: 1.0
.. version-added:: 1.0

.. event:: html-page-context (app, pagename, templatename, context, doctree)

Expand Down Expand Up @@ -406,9 +406,9 @@ These events are emitted by specific builders.
:meth:`.Sphinx.add_js_file` and :meth:`.Sphinx.add_css_file`
(since v3.5.0).

.. versionadded:: 0.4
.. version-added:: 0.4

.. versionchanged:: 1.3
.. version-changed:: 1.3
The return value can now specify a template name.

.. event:: linkcheck-process-uri (app, uri)
Expand All @@ -421,4 +421,4 @@ These events are emitted by specific builders.

The event handlers can modify the URI by returning a string.

.. versionadded:: 4.1
.. version-added:: 4.1
2 changes: 1 addition & 1 deletion doc/extdev/i18n.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ i18n API
Extension internationalization (``i18n``) and localization (``l10n``) using i18n API
------------------------------------------------------------------------------------

.. versionadded:: 1.8
.. version-added:: 1.8

An extension may naturally come with message translations. This is briefly
summarized in :func:`sphinx.locale.get_translation` help.
Expand Down
4 changes: 2 additions & 2 deletions doc/extdev/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ To see an example of application, refer to :ref:`tutorial-extend-build`.
Extension metadata
------------------

.. versionadded:: 1.3
.. version-added:: 1.3

The ``setup()`` function should return a dictionary.
This is treated by Sphinx as metadata of the extension.
Expand All @@ -182,7 +182,7 @@ Metadata keys currently recognized are:
of the stored data change, to ensure Sphinx does not try and load invalid data
from a cached environment.

.. versionadded:: 1.8
.. version-added:: 1.8

``'parallel_read_safe'``
A boolean that specifies if parallel reading of source files
Expand Down
2 changes: 1 addition & 1 deletion doc/extdev/markupapi.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,7 @@ and does not contain any structural elements
with switch_source_input(self.state, self.result):
parsed = nested_parse_to_nodes(self.state, self.result)

.. deprecated:: 1.7
.. version-deprecated:: 1.7

Until Sphinx 1.6, ``sphinx.ext.autodoc.AutodocReporter`` was used for this
purpose. It is replaced by ``switch_source_input()``.
Expand Down
2 changes: 1 addition & 1 deletion doc/extdev/testing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Testing API
.. py:module:: sphinx.testing
:synopsis: Utility functions and pytest fixtures for testing.

.. versionadded:: 1.6
.. version-added:: 1.6

Utility functions and pytest fixtures for testing
are provided in :py:mod:`!sphinx.testing`.
Expand Down
4 changes: 2 additions & 2 deletions doc/internals/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,11 +230,11 @@ New unit tests should be included in the :file:`tests/` directory where necessar
In general, avoid using the ``app`` fixture and ``app.build()``
unless a full integration test is required.

.. versionadded:: 1.8
.. version-added:: 1.8

Sphinx also runs JavaScript tests.

.. versionchanged:: 1.5.2
.. version-changed:: 1.5.2
Sphinx was switched from nose to pytest.


Expand Down
Loading
Loading