From deb736f01b8d391cb90611101f56465f7ce7aed8 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 2 Jul 2025 18:01:06 +0100 Subject: [PATCH 1/2] Hyphenate versioning admonitions Use e.g. 'version-changed' over 'versionchanged'. While the deprecated admonition is marked as deprecated itself in the docs, we do not do anything at runtime since there is almost zero cost to keeping this relative to the work needed for millions of documents to be updated. All our own uses of the 'deprecated' admonition are switched, with some changed to versionchanged where that makes more sense (typically because an attribute or aspect of a feature was deprecated but not the whole feature itself). Changes to the other admonitions will be kept to a separate commit to keep this one reviewable. Signed-off-by: Stephen Finucane --- doc/development/html_themes/index.rst | 2 +- doc/development/html_themes/templating.rst | 10 ++-- doc/extdev/markupapi.rst | 2 +- doc/latex.rst | 3 +- doc/usage/configuration.rst | 9 +-- doc/usage/restructuredtext/directives.rst | 59 ++++++++++++++----- sphinx/addnodes.py | 4 +- sphinx/application.py | 2 +- sphinx/builders/changes.py | 12 +++- sphinx/domains/changeset.py | 17 +++++- tests/roots/test-changes/base.rst | 33 ++++++++--- tests/roots/test-changes/c-api.rst | 4 +- tests/roots/test-changes/library/utils.rst | 6 +- tests/roots/test-intl/versionchange.txt | 16 ++--- .../test-intl/xx/LC_MESSAGES/versionchange.po | 18 +++++- tests/roots/test-root/markup.txt | 29 ++++++--- .../test_builders/test_build_html_5_output.py | 36 ++++++++++- tests/test_intl/test_intl.py | 10 ++-- 18 files changed, 195 insertions(+), 77 deletions(-) diff --git a/doc/development/html_themes/index.rst b/doc/development/html_themes/index.rst index ad2820495ac..16729f4afad 100644 --- a/doc/development/html_themes/index.rst +++ b/doc/development/html_themes/index.rst @@ -214,7 +214,7 @@ If your theme package contains two or more themes, please call .. versionadded:: 1.2 'sphinx_themes' entry_points feature. -.. deprecated:: 1.6 +.. versionchanged:: 1.6 ``sphinx_themes`` entry_points has been deprecated. .. versionadded:: 1.6 diff --git a/doc/development/html_themes/templating.rst b/doc/development/html_themes/templating.rst index 77b43882f86..3b185b63f06 100644 --- a/doc/development/html_themes/templating.rst +++ b/doc/development/html_themes/templating.rst @@ -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 @@ -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. diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst index 184bd2bd8e4..0fdf41fc8f3 100644 --- a/doc/extdev/markupapi.rst +++ b/doc/extdev/markupapi.rst @@ -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()``. diff --git a/doc/latex.rst b/doc/latex.rst index bfc4de73938..e4d8c12038b 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -288,7 +288,8 @@ Keys that you may want to override include: Default: ``''`` - .. deprecated:: 1.5 + .. version-deprecated:: 1.5 + Use ``'atendofbody'`` key instead. Keys that don't need to be overridden unless in special cases are: diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 5babd7e2915..981b386bb7c 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1157,7 +1157,7 @@ Options for source files The recommended encoding is ``'utf-8-sig'``. .. versionadded:: 0.5 - .. deprecated:: 8.3 + .. version-deprecated:: 8.3 Support for source encodings other than UTF-8 is deprecated. Sphinx 10 will only support UTF-8 files. @@ -1586,7 +1586,7 @@ and also make use of these options. .. versionadded:: 3.2 .. versionchanged:: 4.0 It defaults to :code-py:`'inline'`. - .. deprecated:: 4.0 + .. version-deprecated:: 4.0 .. confval:: html_context :type: :code-py:`dict[str, Any]` @@ -1853,7 +1853,7 @@ and also make use of these options. .. versionadded:: 1.0 The ability to use globbing keys and to specify multiple sidebars. - .. deprecated:: 1.7 + .. version-deprecated:: 1.7 A single string value for :confval:`!html_sidebars` will be removed. .. versionchanged:: 2.0 @@ -2103,7 +2103,8 @@ and also make use of these options. `Janome `_ is required. - .. deprecated:: 1.6 + .. version-deprecated:: 1.6 + ``'mecab'``, ``'janome'`` and ``'default'`` is deprecated. To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are also acceptable. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index c75d04c7266..d6688ad53dd 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -537,7 +537,7 @@ Describing changes between versions pair: changes; in version pair: removed; in version -.. rst:directive:: .. versionadded:: version [brief explanation] +.. rst:directive:: .. version-added:: version [brief explanation] This directive documents the version of the project which added the described feature. @@ -553,57 +553,84 @@ Describing changes between versions Example:: - .. versionadded:: 2.5 + .. version-added:: 2.5 The *spam* parameter. - .. versionadded:: 2.5 + .. version-added:: 2.5 The *spam* parameter. -.. rst:directive:: .. versionchanged:: version [brief explanation] +.. rst:directive:: .. version-changed:: version [brief explanation] - Similar to :rst:dir:`versionadded`, but describes when and what changed in + Similar to :rst:dir:`version-added`, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.). Example:: - .. versionchanged:: 2.8 + .. version-changed:: 2.8 The *spam* parameter is now of type *boson*. - .. versionchanged:: 2.8 + .. version-changed:: 2.8 The *spam* parameter is now of type *boson*. -.. rst:directive:: .. deprecated:: version [brief explanation] +.. rst:directive:: .. version-deprecated:: version [brief explanation] - Similar to :rst:dir:`versionadded`, but describes when the feature was + Similar to :rst:dir:`version-added`, but describes when the feature was deprecated. A *brief* explanation can also be given, for example to tell the reader what to use instead. + .. version-added:: 8.3 + Example:: - .. deprecated:: 3.1 + .. version-deprecated:: 3.1 Use :py:func:`spam` instead. - .. deprecated:: 3.1 + .. version-deprecated:: 3.1 Use :py:func:`!spam` instead. -.. rst:directive:: .. versionremoved:: version [brief explanation] +.. rst:directive:: .. version-removed:: version [brief explanation] - Similar to :rst:dir:`versionadded`, but describes when the feature was removed. + Similar to :rst:dir:`version-added`, 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 + .. version-added:: 7.3 Example:: - .. versionremoved:: 4.0 + .. version-removed:: 4.0 The :py:func:`spam` function is more flexible, and should be used instead. - .. versionremoved:: 4.0 + .. version-removed:: 4.0 The :py:func:`!spam` function is more flexible, and should be used instead. +.. rst:directive:: .. versionadded:: version [brief explanation] + + A legacy alias for :rst:dir:`version-added`. + + .. version-deprecated:: 8.3 + +.. rst:directive:: .. versionchanged:: version [brief explanation] + + A legacy alias for :rst:dir:`version-changed`. + + .. version-deprecated:: 8.3 + +.. rst:directive:: .. deprecated:: version [brief explanation] + + A legacy alias for :rst:dir:`version-deprecated`. + + .. version-deprecated:: 8.3 + +.. rst:directive:: .. versionremoved:: version [brief explanation] + + A legacy alias for :rst:dir:`version-removed`. + + .. version-deprecated:: 8.3 + + Presentational ^^^^^^^^^^^^^^ diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 3cf63b6b053..4ce85dabcf2 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -402,8 +402,8 @@ class desc_sig_literal_char(desc_sig_element, _sig_element=True): class versionmodified(nodes.Admonition, nodes.TextElement): """Node for version change entries. - Currently used for "versionadded", "versionchanged", "deprecated" - and "versionremoved" directives. + Currently used for "version-added", "version-changed", "version-deprecated" + and "version-removed" directives, along with their aliases. """ diff --git a/sphinx/application.py b/sphinx/application.py index e8da1e4d058..8538ce72e79 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -1117,7 +1117,7 @@ def setup(app): .. versionchanged:: 0.6 Docutils 0.5-style directive classes are now supported. - .. deprecated:: 1.8 + .. versionchanged:: 1.8 Docutils 0.4-style (function based) directives support is deprecated. .. versionchanged:: 1.8 Add *override* keyword. diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py index 99d46fa0486..6c36e5b8f17 100644 --- a/sphinx/builders/changes.py +++ b/sphinx/builders/changes.py @@ -23,7 +23,7 @@ class ChangesBuilder(Builder): - """Write a summary with all versionadded/changed/deprecated/removed directives.""" + """Write a summary with all version-related directives.""" name = 'changes' epilog = __('The overview file is in %(outdir)s.') @@ -43,6 +43,11 @@ def get_outdated_docs(self) -> str: return str(self.outdir) typemap = { + 'version-added': 'added', + 'version-changed': 'changed', + 'version-deprecated': 'deprecated', + 'version-removed': 'removed', + # deprecated aliases 'versionadded': 'added', 'versionchanged': 'changed', 'deprecated': 'deprecated', @@ -112,6 +117,11 @@ def write_documents(self, _docnames: Set[str]) -> None: f.write(self.templates.render('changes/versionchanges.html', ctx)) hltext = [ + f'.. version-added:: {version}', + f'.. version-changed:: {version}', + f'.. version-deprecated:: {version}', + f'.. version-removed:: {version}', + # deprecated alises f'.. versionadded:: {version}', f'.. versionchanged:: {version}', f'.. deprecated:: {version}', diff --git a/sphinx/domains/changeset.py b/sphinx/domains/changeset.py index e2657ad63ed..23aac222cbf 100644 --- a/sphinx/domains/changeset.py +++ b/sphinx/domains/changeset.py @@ -21,6 +21,12 @@ from sphinx.environment import BuildEnvironment from sphinx.util.typing import ExtensionMetadata, OptionSpec +name_aliases = { + 'version-added': 'versionadded', + 'version-changed': 'versionchanged', + 'version-deprecated': 'deprecated', + 'version-removed': 'versionremoved', +} versionlabels = { 'versionadded': _('Added in version %s'), @@ -56,12 +62,13 @@ class VersionChange(SphinxDirective): option_spec: ClassVar[OptionSpec] = {} def run(self) -> list[Node]: + name = name_aliases.get(self.name, self.name) node = addnodes.versionmodified() node.document = self.state.document self.set_source_info(node) - node['type'] = self.name + node['type'] = name node['version'] = self.arguments[0] - text = versionlabels[self.name] % self.arguments[0] + text = versionlabels[name] % self.arguments[0] if len(self.arguments) == 2: inodes, messages = self.parse_inline( self.arguments[1], lineno=self.lineno + 1 @@ -73,7 +80,7 @@ def run(self) -> list[Node]: messages = [] if self.content: node += self.parse_content_to_nodes() - classes = ['versionmodified', versionlabel_classes[self.name]] + classes = ['versionmodified', versionlabel_classes[name]] if len(node) > 0 and isinstance(node[0], nodes.paragraph): # the contents start with a paragraph if node[0].rawsource: @@ -168,6 +175,10 @@ def get_changesets_for(self, version: str) -> list[ChangeSet]: def setup(app: Sphinx) -> ExtensionMetadata: app.add_domain(ChangeSetDomain) + app.add_directive('version-added', VersionChange) + app.add_directive('version-changed', VersionChange) + app.add_directive('version-deprecated', VersionChange) + app.add_directive('version-removed', VersionChange) app.add_directive('deprecated', VersionChange) app.add_directive('versionadded', VersionChange) app.add_directive('versionchanged', VersionChange) diff --git a/tests/roots/test-changes/base.rst b/tests/roots/test-changes/base.rst index 81d90e66ef4..a6a83e4a282 100644 --- a/tests/roots/test-changes/base.rst +++ b/tests/roots/test-changes/base.rst @@ -1,23 +1,38 @@ Version markup -------------- -.. versionadded:: 0.6 +.. version-added:: 0.6 Some funny **stuff**. -.. versionchanged:: 0.6 +.. version-changed:: 0.6 Even more funny stuff. -.. deprecated:: 0.6 +.. version-deprecated:: 0.6 Boring stuff. -.. versionremoved:: 0.6 +.. version-removed:: 0.6 Goodbye boring stuff. -.. versionadded:: 1.2 +.. version-added:: 1.2 + + First paragraph of version-added. + +.. version-changed:: 1.2 + First paragraph of version-changed. + + Second paragraph of version-changed. - First paragraph of versionadded. +.. version-deprecated:: 1.3 + First paragraph of version-deprecated. -.. versionchanged:: 1.2 - First paragraph of versionchanged. +.. version-added:: 0.6 + Deprecated alias - Second paragraph of versionchanged. +.. version-changed:: 0.6 + Deprecated alias + +.. versionremoved:: 0.6 + Deprecated alias + +.. deprecated:: 0.6 + Deprecated alias diff --git a/tests/roots/test-changes/c-api.rst b/tests/roots/test-changes/c-api.rst index f0ad413cd2e..6ded4afebd5 100644 --- a/tests/roots/test-changes/c-api.rst +++ b/tests/roots/test-changes/c-api.rst @@ -8,7 +8,7 @@ Memory Allocate *n* bytes of memory. - .. versionchanged:: 0.6 + .. version-changed:: 0.6 Can now be replaced with a different allocator. @@ -17,7 +17,7 @@ System Access to the system allocator. -.. versionadded:: 0.6 +.. version-added:: 0.6 .. c:function:: void* Test_SysMalloc(size_t n) diff --git a/tests/roots/test-changes/library/utils.rst b/tests/roots/test-changes/library/utils.rst index 86446995b2f..56675715593 100644 --- a/tests/roots/test-changes/library/utils.rst +++ b/tests/roots/test-changes/library/utils.rst @@ -16,10 +16,10 @@ Classes Class for handling paths. - .. versionadded:: 0.5 + .. version-added:: 0.5 - Innovative new way to handle paths. + Innovative new way to handle paths. - .. deprecated:: 0.6 + .. version-deprecated:: 0.6 So, that was a bad idea it turns out. diff --git a/tests/roots/test-intl/versionchange.txt b/tests/roots/test-intl/versionchange.txt index 764534246c0..69b9ada1858 100644 --- a/tests/roots/test-intl/versionchange.txt +++ b/tests/roots/test-intl/versionchange.txt @@ -3,16 +3,16 @@ i18n with versionchange ============================ -.. deprecated:: 1.0 - This is the *first* paragraph of deprecated. +.. version-deprecated:: 1.0 + This is the *first* paragraph of version-deprecated. - This is the *second* paragraph of deprecated. + This is the *second* paragraph of version-deprecated. -.. versionadded:: 1.0 - This is the *first* paragraph of versionadded. +.. version-added:: 1.0 + This is the *first* paragraph of version-added. -.. versionchanged:: 1.0 +.. version-changed:: 1.0 - This is the *first* paragraph of versionchanged. + This is the *first* paragraph of version-changed. -.. versionremoved:: 1.0 This is the *first* paragraph of versionremoved. +.. version-removed:: 1.0 This is the *first* paragraph of version-removed. diff --git a/tests/roots/test-intl/xx/LC_MESSAGES/versionchange.po b/tests/roots/test-intl/xx/LC_MESSAGES/versionchange.po index b1d786580f0..8f1b88bcaca 100644 --- a/tests/roots/test-intl/xx/LC_MESSAGES/versionchange.po +++ b/tests/roots/test-intl/xx/LC_MESSAGES/versionchange.po @@ -19,12 +19,24 @@ msgstr "" msgid "i18n with versionchange" msgstr "I18N WITH VERSIONCHANGE" +msgid "This is the *first* paragraph of version-deprecated." +msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-DEPRECATED." + +msgid "This is the *second* paragraph of version-deprecated." +msgstr "THIS IS THE *SECOND* PARAGRAPH OF VERSION-DEPRECATED." + +msgid "This is the *first* paragraph of version-added." +msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-ADDED." + +msgid "This is the *first* paragraph of version-changed." +msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-CHANGED." + +msgid "This is the *first* paragraph of version-removed." +msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-REMOVED." + msgid "This is the *first* paragraph of deprecated." msgstr "THIS IS THE *FIRST* PARAGRAPH OF DEPRECATED." -msgid "This is the *second* paragraph of deprecated." -msgstr "THIS IS THE *SECOND* PARAGRAPH OF DEPRECATED." - msgid "This is the *first* paragraph of versionadded." msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSIONADDED." diff --git a/tests/roots/test-root/markup.txt b/tests/roots/test-root/markup.txt index 0a7b6cb2c92..8f5e026a25f 100644 --- a/tests/roots/test-root/markup.txt +++ b/tests/roots/test-root/markup.txt @@ -292,27 +292,38 @@ Figures Version markup -------------- -.. versionadded:: 0.6 +.. version-added:: 0.6 Some funny **stuff**. -.. versionchanged:: 0.6 +.. version-changed:: 0.6 Even more funny stuff. -.. deprecated:: 0.6 +.. version-deprecated:: 0.6 Boring stuff. -.. versionremoved:: 0.6 +.. version-removed:: 0.6 Goodbye boring stuff. -.. versionadded:: 1.2 +.. version-added:: 1.2 + + First paragraph of version-added. + +.. version-changed:: 1.2 + First paragraph of version-changed. - First paragraph of versionadded. + Second paragraph of version-changed. -.. versionchanged:: 1.2 - First paragraph of versionchanged. +.. version-added:: 0.6 + Deprecated alias for version-added. - Second paragraph of versionchanged. +.. version-changed:: 0.6 + Deprecated alias for version-changed. +.. deprecated:: 0.6 + Deprecated alias for version-deprecated. + +.. versionremoved:: 0.6 + Deprecated alias for version-removed. Code blocks ----------- diff --git a/tests/test_builders/test_build_html_5_output.py b/tests/test_builders/test_build_html_5_output.py index db9dd8a749c..6798482f628 100644 --- a/tests/test_builders/test_build_html_5_output.py +++ b/tests/test_builders/test_build_html_5_output.py @@ -205,23 +205,53 @@ def checker(nodes: Iterable[Element]) -> Literal[True]: ( 'markup.html', ".//div[@class='versionadded']/p/span", - tail_check('First paragraph of versionadded'), + tail_check('First paragraph of version-added'), + ), + ( + 'markup.html', + ".//div[@class='versionadded']/p/span", + tail_check('Deprecated alias for version-added'), ), ( 'markup.html', ".//div[@class='versionchanged']/p/span", - tail_check('First paragraph of versionchanged'), + tail_check('First paragraph of version-changed'), ), ( 'markup.html', ".//div[@class='versionchanged']/p", - 'Second paragraph of versionchanged', + 'Second paragraph of version-changed', + ), + ( + 'markup.html', + ".//div[@class='versionchanged']/p/span", + tail_check('Deprecated alias for version-changed'), + ), + ( + 'markup.html', + ".//div[@class='deprecated']/p/span", + 'Deprecated since version 0.6: ', + ), + ( + 'markup.html', + ".//div[@class='deprecated']/p/span", + tail_check('Boring stuff.'), + ), + ( + 'markup.html', + ".//div[@class='deprecated']/p/span", + tail_check('Deprecated alias for version-deprecated'), ), ( 'markup.html', ".//div[@class='versionremoved']/p/span", 'Removed in version 0.6: ', ), + ( + 'markup.html', + ".//div[@class='versionremoved']/p/span", + tail_check('Deprecated alias for version-removed'), + ), # footnote reference ('markup.html', ".//a[@class='footnote-reference brackets']", r'1'), # created by reference lookup diff --git a/tests/test_intl/test_intl.py b/tests/test_intl/test_intl.py index d43c029d4d6..2375c1a6687 100644 --- a/tests/test_intl/test_intl.py +++ b/tests/test_intl/test_intl.py @@ -1101,29 +1101,29 @@ def get_content(result, name): expect1 = ( """

Deprecated since version 1.0: """ - """THIS IS THE FIRST PARAGRAPH OF DEPRECATED.

\n""" - """

THIS IS THE SECOND PARAGRAPH OF DEPRECATED.

\n""" + """THIS IS THE FIRST PARAGRAPH OF VERSION-DEPRECATED.

\n""" + """

THIS IS THE SECOND PARAGRAPH OF VERSION-DEPRECATED.

\n""" ) matched_content = get_content(result, 'deprecated') assert matched_content == expect1 expect2 = ( """

Added in version 1.0: """ - """THIS IS THE FIRST PARAGRAPH OF VERSIONADDED.

\n""" + """THIS IS THE FIRST PARAGRAPH OF VERSION-ADDED.

\n""" ) matched_content = get_content(result, 'versionadded') assert matched_content == expect2 expect3 = ( """

Changed in version 1.0: """ - """THIS IS THE FIRST PARAGRAPH OF VERSIONCHANGED.

\n""" + """THIS IS THE FIRST PARAGRAPH OF VERSION-CHANGED.

\n""" ) matched_content = get_content(result, 'versionchanged') assert matched_content == expect3 expect4 = ( """

Removed in version 1.0: """ - """THIS IS THE FIRST PARAGRAPH OF VERSIONREMOVED.

\n""" + """THIS IS THE FIRST PARAGRAPH OF VERSION-REMOVED.

\n""" ) matched_content = get_content(result, 'versionremoved') assert matched_content == expect4 From 6e01dbffb5644dca95336220a91dd2875184d8ca Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 3 Jul 2025 17:35:43 +0100 Subject: [PATCH 2/2] docs: Use hyphenated versioning admonitions Signed-off-by: Stephen Finucane --- doc/development/howtos/builders.rst | 2 +- doc/development/html_themes/index.rst | 20 +- doc/development/html_themes/templating.rst | 12 +- doc/extdev/event_callbacks.rst | 38 +- doc/extdev/i18n.rst | 2 +- doc/extdev/index.rst | 4 +- doc/extdev/testing.rst | 2 +- doc/internals/contributing.rst | 4 +- doc/latex.rst | 256 +++++----- doc/man/sphinx-apidoc.rst | 6 +- doc/man/sphinx-build.rst | 78 +-- doc/man/sphinx-quickstart.rst | 6 +- doc/usage/advanced/intl.rst | 8 +- doc/usage/advanced/websupport/api.rst | 2 +- doc/usage/advanced/websupport/index.rst | 2 +- .../advanced/websupport/searchadapters.rst | 2 +- .../advanced/websupport/storagebackends.rst | 2 +- doc/usage/builders/index.rst | 46 +- doc/usage/configuration.rst | 472 +++++++++--------- doc/usage/domains/c.rst | 32 +- doc/usage/domains/cpp.rst | 32 +- doc/usage/domains/index.rst | 10 +- doc/usage/domains/javascript.rst | 14 +- doc/usage/domains/mathematics.rst | 4 +- doc/usage/domains/python.rst | 80 +-- doc/usage/domains/restructuredtext.rst | 4 +- doc/usage/domains/standard.rst | 8 +- doc/usage/extensions/apidoc.rst | 2 +- doc/usage/extensions/autodoc.rst | 152 +++--- doc/usage/extensions/autosectionlabel.rst | 2 +- doc/usage/extensions/autosummary.rst | 44 +- doc/usage/extensions/coverage.rst | 14 +- doc/usage/extensions/doctest.rst | 16 +- doc/usage/extensions/duration.rst | 2 +- doc/usage/extensions/extlinks.rst | 6 +- doc/usage/extensions/githubpages.rst | 4 +- doc/usage/extensions/graphviz.rst | 48 +- doc/usage/extensions/imgconverter.rst | 6 +- doc/usage/extensions/inheritance.rst | 12 +- doc/usage/extensions/intersphinx.rst | 12 +- doc/usage/extensions/linkcode.rst | 2 +- doc/usage/extensions/math.rst | 26 +- doc/usage/extensions/napoleon.rst | 14 +- doc/usage/extensions/todo.rst | 10 +- doc/usage/extensions/viewcode.rst | 14 +- doc/usage/referencing.rst | 10 +- doc/usage/restructuredtext/basics.rst | 6 +- doc/usage/restructuredtext/directives.rst | 118 ++--- doc/usage/restructuredtext/field-lists.rst | 8 +- doc/usage/restructuredtext/roles.rst | 12 +- doc/usage/theming.rst | 12 +- sphinx/__init__.py | 2 +- sphinx/addnodes.py | 2 +- sphinx/application.py | 112 ++--- sphinx/domains/__init__.py | 2 +- sphinx/domains/_index.py | 2 +- sphinx/domains/python/__init__.py | 4 +- sphinx/domains/std/__init__.py | 4 +- sphinx/ext/linkcode.py | 2 +- sphinx/locale/__init__.py | 4 +- sphinx/search/__init__.py | 2 +- sphinx/util/docutils.py | 34 +- sphinx/util/logging.py | 2 +- sphinx/util/parsing.py | 2 +- 64 files changed, 937 insertions(+), 937 deletions(-) diff --git a/doc/development/howtos/builders.rst b/doc/development/howtos/builders.rst index ff1b6cf3f00..e814f672622 100644 --- a/doc/development/howtos/builders.rst +++ b/doc/development/howtos/builders.rst @@ -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 diff --git a/doc/development/html_themes/index.rst b/doc/development/html_themes/index.rst index 16729f4afad..862e837feee 100644 --- a/doc/development/html_themes/index.rst +++ b/doc/development/html_themes/index.rst @@ -3,7 +3,7 @@ HTML theme development ====================== -.. versionadded:: 0.6 +.. version-added:: 0.6 .. note:: @@ -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_``. -.. versionadded:: 7.3 +.. version-added:: 7.3 ``theme.toml`` support. .. _TOML: https://toml.io/en/ @@ -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_``. -.. versionadded:: 1.7 +.. version-added:: 1.7 sidebar settings -.. versionchanged:: 5.1 +.. version-changed:: 5.1 The stylesheet setting accepts multiple CSS filenames @@ -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: @@ -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. -.. versionchanged:: 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. @@ -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:: @@ -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`_. diff --git a/doc/development/html_themes/templating.rst b/doc/development/html_themes/templating.rst index 3b185b63f06..037f718210d 100644 --- a/doc/development/html_themes/templating.rst +++ b/doc/development/html_themes/templating.rst @@ -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 @@ -331,7 +331,7 @@ 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 @@ -339,7 +339,7 @@ in the future. 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 @@ -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 @@ -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 diff --git a/doc/extdev/event_callbacks.rst b/doc/extdev/event_callbacks.rst index aec9a47e848..9c47f6d582e 100644 --- a/doc/extdev/event_callbacks.rst +++ b/doc/extdev/event_callbacks.rst @@ -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) @@ -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) @@ -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) @@ -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) @@ -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) @@ -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. @@ -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) @@ -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) @@ -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) @@ -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) @@ -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) @@ -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) @@ -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) @@ -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 ----------------------- @@ -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) @@ -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) @@ -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 diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst index 8542ae684b6..b34d4a73e91 100644 --- a/doc/extdev/i18n.rst +++ b/doc/extdev/i18n.rst @@ -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. diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 2eff8f0738d..0ff3e125d10 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -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. @@ -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 diff --git a/doc/extdev/testing.rst b/doc/extdev/testing.rst index db03855bc43..bd84b771fad 100644 --- a/doc/extdev/testing.rst +++ b/doc/extdev/testing.rst @@ -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`. diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst index de4224d7bc3..3978814ea01 100644 --- a/doc/internals/contributing.rst +++ b/doc/internals/contributing.rst @@ -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. diff --git a/doc/latex.rst b/doc/latex.rst index e4d8c12038b..129bf867576 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -119,7 +119,7 @@ Keys that you may want to override include: Default: ``'0.75bp'`` - .. versionadded:: 1.5 + .. version-added:: 1.5 ``'passoptionstopackages'`` A string which will be positioned early in the preamble, designed to @@ -133,7 +133,7 @@ Keys that you may want to override include: Default: ``''`` - .. versionadded:: 1.4 + .. version-added:: 1.4 ``'babel'`` "babel" package inclusion, default :code-tex:`r'\\usepackage{babel}'` (the @@ -157,18 +157,18 @@ Keys that you may want to override include: Default: :code-tex:`r'\\usepackage{babel}'` (for Japanese documents) - .. versionchanged:: 1.5 + .. version-changed:: 1.5 For :confval:`latex_engine` set to ``'xelatex'``, the default is ``'\\usepackage{polyglossia}\n\\setmainlanguage{}'``. - .. versionchanged:: 1.6 + .. version-changed:: 1.6 ``'lualatex'`` uses same default setting as ``'xelatex'`` - .. versionchanged:: 1.7.6 + .. version-changed:: 1.7.6 For French with ``'xelatex'`` (not ``'lualatex'``) the default is to use ``babel``, not ``polyglossia``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 For French with ``'lualatex'`` the default is to use ``babel``. .. _fontpkg: @@ -187,22 +187,22 @@ Keys that you may want to override include: via :ref:`fontenc`) are used to set up the OpenType fonts GNU FreeSerif, FreeSans, and FreeMono (scaled with ratio ``0.9``) as document fonts. - .. versionchanged:: 1.2 + .. version-changed:: 1.2 Defaults to ``''`` when the :confval:`language` uses the Cyrillic script. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Incorporates some font substitution commands to help support occasional Greek or Cyrillic in a document using ``'pdflatex'`` engine. At 4.0.0 these commands were moved to the ``'fontsubstitution'`` key. - .. versionchanged:: 4.0.0 + .. version-changed:: 4.0.0 The default font setting was changed. As shown above it still uses Times and Helvetica clones for serif and sans serif, but via better, more complete TeX fonts and associated LaTeX packages. The monospace font has been changed to better match the Times clone. - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 The monospace font FreeMono used with Unicode engines is loaded at scale ``0.9``. This replaces the former mechanism via :ref:`fvset` which configured code-blocks to use :code-tex:`\\small`. Inline literals now @@ -254,14 +254,14 @@ Keys that you may want to override include: Default: ``'htbp'`` (here, top, bottom, page) - .. versionadded:: 1.3 + .. version-added:: 1.3 ``'atendofbody'`` Additional document content (right before the indices). Default: ``''`` - .. versionadded:: 1.5 + .. version-added:: 1.5 ``'extrapackages'`` Additional LaTeX packages. For example: @@ -281,7 +281,7 @@ Keys that you may want to override include: Default: ``''`` - .. versionadded:: 2.3 + .. version-added:: 2.3 ``'footer'`` Additional footer content (before the indices). @@ -301,9 +301,9 @@ Keys that don't need to be overridden unless in special cases are: Default: ``''`` - .. versionadded:: 1.2 + .. version-added:: 1.2 - .. versionchanged:: 1.6 + .. version-changed:: 1.6 Added this documentation. ``'maxlistdepth'`` @@ -324,7 +324,7 @@ Keys that don't need to be overridden unless in special cases are: Default: ``6`` - .. versionadded:: 1.5 + .. version-added:: 1.5 ``'inputenc'`` "inputenc" package inclusion. @@ -354,7 +354,7 @@ Keys that don't need to be overridden unless in special cases are: such filenames for PDF via LaTeX output. But this is broken if ``utf8x`` is in use. - .. versionchanged:: 1.4.3 + .. version-changed:: 1.4.3 Previously :code-tex:`r'\\usepackage[utf8]{inputenc}'` was used for all compilers. @@ -363,7 +363,7 @@ Keys that don't need to be overridden unless in special cases are: Default: :code-tex:`r'\\usepackage{cmap}'` - .. versionadded:: 1.2 + .. version-added:: 1.2 .. _fontenc: @@ -393,29 +393,29 @@ Keys that don't need to be overridden unless in special cases are: package ``fontspec`` (with some extras described below) and selects the GNU FreeSerif font as body font. See :ref:`fontpkg`. - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Defaults to :code-tex:`r'\\usepackage{fontspec}'` if :confval:`latex_engine` is set to ``'xelatex'``. - .. versionchanged:: 1.6 + .. version-changed:: 1.6 Defaults to :code-tex:`r'\\usepackage{fontspec}'` if :confval:`latex_engine` is set to ``'lualatex'``. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 ``'lualatex'`` executes additionally :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` to disable TeX ligatures for ``<<`` and ``>>``. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Extra LaTeX configuration is automatically executed if ``LGR``, ``T2A``, or ``X2`` are detected in this key, in order to support occasional Greek or Cyrillic with ``'pdflatex'``. - .. versionchanged:: 2.2.1 + .. version-changed:: 2.2.1 Documents having Greek as main language default to ``'xelatex'`` and should not set the :ref:`fontenc` key, which will load ``fontspec``. - .. versionchanged:: 2.3.0 + .. version-changed:: 2.3.0 ``'xelatex'`` executes :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` in order to avoid contractions of ``--`` into en-dash and also transforms of @@ -430,7 +430,7 @@ Keys that don't need to be overridden unless in special cases are: Ignored with :confval:`latex_engine` other than ``'pdflatex'``. - .. versionadded:: 4.0.0 + .. version-added:: 4.0.0 ``'textgreek'`` For the support of occasional Greek letters. @@ -448,7 +448,7 @@ Keys that don't need to be overridden unless in special cases are: Default: :code-tex:`r'\\usepackage{textalpha}'` or ``''`` if ``fontenc`` does not include the ``LGR`` option. - .. versionadded:: 2.0 + .. version-added:: 2.0 ``'geometry'`` "geometry" package inclusion, defaults to @@ -463,16 +463,16 @@ Keys that don't need to be overridden unless in special cases are: which can be customized via corresponding :ref:`'sphinxsetup' options `. - .. versionadded:: 1.5 + .. version-added:: 1.5 - .. versionchanged:: 1.5.2 + .. version-changed:: 1.5.2 ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``. - .. versionadded:: 1.5.3 + .. version-added:: 1.5.3 The :ref:`'sphinxsetup' keys for the margins `. - .. versionchanged:: 1.5.3 + .. version-changed:: 1.5.3 The location in the LaTeX file has been moved to after :code-tex:`\\usepackage{sphinx}` and :code-tex:`\\sphinxsetup{..}`, hence also after @@ -491,7 +491,7 @@ Keys that don't need to be overridden unless in special cases are: Loading of packages "hyperref" and "hypcap" is mandatory. - .. versionadded:: 1.5 + .. version-added:: 1.5 Previously this was done from inside :file:`sphinx.sty`. ``'maketitle'`` @@ -507,11 +507,11 @@ Keys that don't need to be overridden unless in special cases are: Default: :code-tex:`r'\\sphinxmaketitle'` - .. versionchanged:: 1.8.3 + .. version-changed:: 1.8.3 Original :code-tex:`\\maketitle` from document class is not overwritten, hence is reusable as part of some custom setting for this key. - .. versionadded:: 1.8.3 + .. version-added:: 1.8.3 :code-tex:`\\sphinxbackoftitlepage` optional macro. It can also be defined inside ``'preamble'`` key rather than this one. @@ -531,7 +531,7 @@ Keys that don't need to be overridden unless in special cases are: Default: :code-tex:`r'\\sphinxtableofcontents'` - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Previously the meaning of :code-tex:`\\tableofcontents` itself was modified by Sphinx. This created an incompatibility with dedicated packages modifying it also such as "tocloft" or "etoc". @@ -542,9 +542,9 @@ Keys that don't need to be overridden unless in special cases are: Default: :code-tex:`'\\n\\n\\\\bigskip\\\\hrule\\\\bigskip\\n\\n'` - .. versionadded:: 1.2 + .. version-added:: 1.2 - .. versionchanged:: 1.6 + .. version-changed:: 1.6 Remove unneeded ``{}`` formerly located after :code-tex:`\\hrule`. ``'makeindex'`` @@ -581,22 +581,22 @@ Keys that don't need to be overridden unless in special cases are: Default: :code-tex:`r'\\fvset{fontsize=auto}'` - .. versionadded:: 1.8 + .. version-added:: 1.8 - .. versionchanged:: 2.0 + .. version-changed:: 2.0 For ``'xelatex'`` and ``'lualatex'`` defaults to :code-tex:`r'\\fvset{fontsize=\\small}'` as this is adapted to the relative widths of the FreeFont family. - .. versionchanged:: 4.0.0 + .. version-changed:: 4.0.0 Changed default for ``'pdflatex'``. Previously it was using :code-tex:`r'\\fvset{fontsize=\\small}'`. - .. versionchanged:: 4.1.0 + .. version-changed:: 4.1.0 Changed default for Chinese documents to :code-tex:`r'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'` - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 Changed default for ``'xelatex'`` and ``'lualatex'`` to be also :code-tex:`r'\\fvset{fontsize=auto}'`. The rescaling for default monospace font FreeMono is now set via the LaTeX package ``fontspec`` @@ -616,7 +616,7 @@ Keys that are set by other options and therefore should not be overridden are: The ``sphinxsetup`` configuration setting ----------------------------------------- -.. versionadded:: 1.5 +.. version-added:: 1.5 The ``'sphinxsetup'`` key of :ref:`latex_elements ` provides a LaTeX-type customization interface:: @@ -682,7 +682,7 @@ The color used in the above example is available from having passed the Default: ``5`` - .. versionadded:: 4.0.0 + .. version-added:: 4.0.0 .. _latexsphinxsetuphmargin: @@ -710,7 +710,7 @@ The color used in the above example is available from having passed the 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw', - .. versionadded:: 1.5.3 + .. version-added:: 1.5.3 ``marginpar`` The :code-tex:`\\marginparwidth` LaTeX dimension. For Japanese documents, @@ -719,14 +719,14 @@ The color used in the above example is available from having passed the Default: ``0.5in`` - .. versionadded:: 1.5.3 + .. version-added:: 1.5.3 ``mathnumsep`` This defaults to the string (without quotes!) as set by :confval:`math_numsep` (which itself defaults to ``'.'``). Use it if a different setting is needed for LaTeX output. - .. versionadded:: 8.1.0 + .. version-added:: 8.1.0 ``verbatimwithframe`` Boolean to specify if :rst:dir:`code-block`\ s and literal includes are @@ -767,7 +767,7 @@ The color used in the above example is available from having passed the Default: ``false`` - .. versionadded:: 3.5.0 + .. version-added:: 3.5.0 ``verbatimmaxoverfull`` A number. If an unbreakable long string has length larger than the total @@ -777,7 +777,7 @@ The color used in the above example is available from having passed the Default: ``3`` - .. versionadded:: 3.5.0 + .. version-added:: 3.5.0 ``verbatimmaxunderfull`` A number. If ``verbatimforcewraps`` mode applies, and if after applying @@ -800,7 +800,7 @@ The color used in the above example is available from having passed the Default: ``100`` - .. versionadded:: 3.5.0 + .. version-added:: 3.5.0 ``verbatimhintsturnover`` Boolean to specify if code-blocks display "continued on next page" and @@ -808,8 +808,8 @@ The color used in the above example is available from having passed the Default: ``true`` - .. versionadded:: 1.6.3 - .. versionchanged:: 1.7 + .. version-added:: 1.6.3 + .. version-changed:: 1.7 the default changed from ``false`` to ``true``. ``verbatimcontinuedalign``, ``verbatimcontinuesalign`` @@ -818,7 +818,7 @@ The color used in the above example is available from having passed the Default: ``r`` - .. versionadded:: 1.7 + .. version-added:: 1.7 ``parsedliteralwraps`` Boolean to specify if long lines in :dudir:`parsed-literal`\ 's contents @@ -826,7 +826,7 @@ The color used in the above example is available from having passed the Default: ``true`` - .. versionadded:: 1.5.2 + .. version-added:: 1.5.2 set this option value to ``false`` to recover former behavior. ``inlineliteralwraps`` @@ -838,10 +838,10 @@ The color used in the above example is available from having passed the Default: ``true`` - .. versionadded:: 1.5 + .. version-added:: 1.5 set this option value to ``false`` to recover former behavior. - .. versionchanged:: 2.3.0 + .. version-changed:: 2.3.0 added potential breakpoint at ``\`` characters. ``verbatimvisiblespace`` @@ -858,7 +858,7 @@ The color used in the above example is available from having passed the \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} - .. versionchanged:: 1.5 + .. version-changed:: 1.5 The breaking of long code lines was added at 1.4.2. The default definition of the continuation symbol was changed at 1.5 to accommodate various font sizes (e.g. code-blocks can be in footnotes). @@ -879,7 +879,7 @@ The color used in the above example is available from having passed the .. _xcolor: https://ctan.org/pkg/xcolor - .. versionchanged:: 5.3.0 + .. version-changed:: 5.3.0 Formerly only the :code-tex:`\\definecolor` syntax was accepted. ``TitleColor`` @@ -904,7 +904,7 @@ The color used in the above example is available from having passed the Default: ``{RGB}{242,242,242}`` (same as ``{gray}{0.95}``). - .. versionchanged:: 6.0.0 + .. version-changed:: 6.0.0 Formerly, it was ``{rgb}{1,1,1}`` (white). @@ -913,7 +913,7 @@ The color used in the above example is available from having passed the Default: ``{RGB}{32,32,32}`` - .. versionchanged:: 6.0.0 + .. version-changed:: 6.0.0 Formerly it was ``{rgb}{0,0,0}`` (black). @@ -922,7 +922,7 @@ The color used in the above example is available from having passed the Default: ``{rgb}{0.878,1,1}`` - .. versionadded:: 1.6.6 + .. version-added:: 1.6.6 .. _tablecolors: @@ -944,7 +944,7 @@ The color used in the above example is available from having passed the There is also ``TableMergeColorHeader``. If used, sets a specific color for merged single-row cells in the header. - .. versionadded:: 5.3.0 + .. version-added:: 5.3.0 ``TableRowColorOdd`` Sets the background color for odd rows in tables (the row count starts at @@ -956,7 +956,7 @@ The color used in the above example is available from having passed the There is also ``TableMergeColorOdd``. - .. versionadded:: 5.3.0 + .. version-added:: 5.3.0 ``TableRowColorEven`` Sets the background color for even rows in tables. @@ -965,7 +965,7 @@ The color used in the above example is available from having passed the There is also ``TableMergeColorEven``. - .. versionadded:: 5.3.0 + .. version-added:: 5.3.0 ``verbatimsep`` The separation between code lines and the frame. @@ -1022,30 +1022,30 @@ The color used in the above example is available from having passed the interface (see the :ref:`additionalcss` section for these extra ``'sphinxsetup'`` keys). - .. versionadded:: 7.4.0 + .. version-added:: 7.4.0 |notebdcolors| The color for the admonition border. Default: ``{RGB}{134,152,155}``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 |notebgcolors| The color for the admonition background. Default: ``{RGB}{247,247,247}``. - .. versionadded:: 6.2.0 + .. version-added:: 6.2.0 - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 |notetextcolors| The color for the admonition contents. Default: unset (contents text uses ambient text color, a priori black) - .. versionadded:: 6.2.0 + .. version-added:: 6.2.0 To be considered experimental until 7.0.0. These options have aliases ``div.note_TeXcolor`` (etc) described in :ref:`additionalcss`. Using @@ -1058,7 +1058,7 @@ The color used in the above example is available from having passed the Default: empty - .. versionadded:: 6.2.0 + .. version-added:: 6.2.0 To be considered experimental until 7.0.0. These options have aliases ``div.note_TeXextras`` (etc) described in :ref:`additionalcss`. @@ -1077,7 +1077,7 @@ The color used in the above example is available from having passed the Default: ``{RGB}{148,0,0}`` except for ``error`` which uses ``red``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 .. only:: latex @@ -1086,14 +1086,14 @@ The color used in the above example is available from having passed the Default: ``{RGB}{148,0,0}`` except for ``error`` which uses ``red``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 |warningbgcolors| The background color for the admonition background. Default: ``{RGB}{247,247,247}``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 |warningborders| The width of the admonition frame. See @@ -1102,7 +1102,7 @@ The color used in the above example is available from having passed the Default: ``1pt`` except for ``error`` which uses ``1.25pt``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 ``AtStartFootnote`` LaTeX macros inserted at the start of the footnote text at bottom of page, @@ -1116,7 +1116,7 @@ The color used in the above example is available from having passed the Default: :code-tex:`\\leavevmode\\unskip` - .. versionadded:: 1.5 + .. version-added:: 1.5 ``HeaderFamily`` default :code-tex:`\\sffamily\\bfseries`. Sets the font used by headings. @@ -1156,12 +1156,12 @@ The color used in the above example is available from having passed the Additional CSS-like ``'sphinxsetup'`` keys ------------------------------------------- -.. versionadded:: 5.1.0 +.. version-added:: 5.1.0 For :rst:dir:`code-block`, :dudir:`topic` and contents_ directive, and strong-type admonitions (:dudir:`warning`, :dudir:`error`, ...). -.. versionadded:: 6.2.0 +.. version-added:: 6.2.0 Also the :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip` admonitions can be styled this way. Using for them *any* of the listed @@ -1170,7 +1170,7 @@ Additional CSS-like ``'sphinxsetup'`` keys ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...). -.. versionadded:: 7.4.0 +.. version-added:: 7.4.0 For *all* admonition types, the default configuration does set a background color (hence the richer ``sphinxheavybox`` is always used). @@ -1183,11 +1183,11 @@ Additional CSS-like ``'sphinxsetup'`` keys set the foreground and background colors for the title as well as the LaTeX code for the icon. -.. versionadded:: 7.4.0 +.. version-added:: 7.4.0 Customizability of the :rst:dir:`seealso` and :rst:dir:`todo` directives. -.. versionadded:: 8.1.0 +.. version-added:: 8.1.0 Separate customizability and new defaults for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. @@ -1272,10 +1272,10 @@ forget the underscore separating the prefix from the property names. * ``1pt`` for :dudir:`warning` and other "strong" admonitions except :dudir:`error` which uses ``1.25pt``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 Changed defaults for :dudir:`topic` and :dudir:`error`. - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 Distinct from :dudir:`topic` defaults for :dudir:`sidebar`. - ``_box-decoration-break`` can be set to either ``clone`` or @@ -1300,7 +1300,7 @@ forget the underscore separating the prefix from the property names. * ``6pt``, ``6.5pt``, ``6pt``, ``6.5pt`` for the strong admonition types except :dudir:`error` which uses horizontal padding of ``6.25pt``. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 All defaults were changed, except for :rst:dir:`code-block`. Admonitions are set-up so that left (or right) padding plus left (or right) @@ -1308,7 +1308,7 @@ forget the underscore separating the prefix from the property names. vertically across admonition types on same page in PDF. This is only a property of defaults, not a constraint on possible user choices. - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`. - | ``_border-top-left-radius``, @@ -1330,11 +1330,11 @@ forget the underscore separating the prefix from the property names. :dudir:`tip`, * ``0pt``, i.e. straight corners for all other directives. - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 :dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one) rounded corners. - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`. See a remark above about traps with spaces in LaTeX. @@ -1352,7 +1352,7 @@ forget the underscore separating the prefix from the property names. The default is ``none`` *except* for the contents_ directive which uses ``4pt 4pt``. - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 No shadow per default for :dudir:`topic` and :dudir:`sidebar`. - | ``_border-TeXcolor``, @@ -1429,7 +1429,7 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and - All directives support ``box-decoration-break`` to be set to ``slice``. - .. versionchanged:: 6.2.0 + .. version-changed:: 6.2.0 Formerly, only :rst:dir:`code-block` did. The default remains ``clone`` for all other directives, but this will probably change at @@ -1437,7 +1437,7 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and - The corners of rounded boxes may be elliptical. - .. versionchanged:: 6.2.0 + .. version-changed:: 6.2.0 Formerly, only circular rounded corners were supported and a rounded corner forced the whole frame to use the same constant width from @@ -1446,7 +1446,7 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and - Inset shadows are incompatible with rounded corners. In case both are specified the inset shadow will simply be ignored. - .. versionchanged:: 6.2.0 + .. version-changed:: 6.2.0 Formerly it was to the contrary the rounded corners which were ignored in case an inset shadow was specified. @@ -1524,7 +1524,7 @@ definition files. :confval:`latex_additional_files` list. Check the LaTeX build repertory for the filenames and contents. -.. versionchanged:: 4.0.0 +.. version-changed:: 4.0.0 split of :file:`sphinx.sty` into multiple smaller units, to facilitate customization of many aspects simultaneously. @@ -1558,20 +1558,20 @@ Macros ``\sphinxtypeparam``; ``\emph{#1}`` ``\sphinxoptional``; ``[#1]`` with larger brackets, see source - .. versionadded:: 1.4.5 + .. version-added:: 1.4.5 Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict with LaTeX packages. - .. versionadded:: 1.8 + .. version-added:: 1.8 :code-tex:`\\sphinxguilabel` - .. versionadded:: 3.0 + .. version-added:: 3.0 :code-tex:`\\sphinxkeyboard` - .. versionadded:: 6.2.0 + .. version-added:: 6.2.0 :code-tex:`\\sphinxparam`, :code-tex:`\\sphinxsamedocref` - .. versionadded:: 7.1.0 + .. version-added:: 7.1.0 :code-tex:`\\sphinxparamcomma` which defaults to a comma followed by a space and :code-tex:`\\sphinxparamcommaoneperline`. It is sed for one-parameter-per-line signatures (see @@ -1640,40 +1640,40 @@ Macros admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not use :code-tex:`\\sphinxremovefinalcolon` as they don't need it. - .. versionadded:: 1.5 + .. version-added:: 1.5 These macros were formerly hard-coded as non customizable :code-tex:`\\texttt`, :code-tex:`\\emph`, etc... - .. versionadded:: 1.6 + .. version-added:: 1.6 :code-tex:`\\sphinxstyletheadfamily` which defaults to :code-tex:`\\sffamily` and allows multiple paragraphs in header cells of tables. - .. versionadded:: 1.6.3 + .. version-added:: 1.6.3 :code-tex:`\\sphinxstylecodecontinued` and :code-tex:`\\sphinxstylecodecontinues`. - .. versionadded:: 1.8 + .. version-added:: 1.8 :code-tex:`\\sphinxstyleindexlettergroup`, :code-tex:`\\sphinxstyleindexlettergroupDefault`. - .. versionadded:: 6.2.0 + .. version-added:: 6.2.0 :code-tex:`\\sphinxstylenotetitle` et al. The ``#1`` is the localized name of the directive, with a final colon. Wrap it as :code-tex:`\\sphinxremovefinalcolon{#1}` if this final colon is to be removed. - .. versionadded:: 7.4.0 + .. version-added:: 7.4.0 Added the :code-tex:`\\sphinxdotitlerowwithicon` LaTeX command. - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 :code-tex:`\\sphinxdotitlerowwithicon` now detects automatically if an icon is associated or not with the rendered element used as first argument. - .. versionadded:: 8.1.0 Make :code-tex:`\\sphinxdotitlerow` an alias to + .. version-added:: 8.1.0 Make :code-tex:`\\sphinxdotitlerow` an alias to :code-tex:`\\sphinxdotitlerowwithicon`. - .. versionadded:: 8.1.0 + .. version-added:: 8.1.0 Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are also styled using :code-tex:`\\sphinxdotitlerow` (they have no default icons associated with them). @@ -1684,10 +1684,10 @@ Macros :code-tex:`\\sphinxtableofcontentshook` is executed during its expansion right before :code-tex:`\\tableofcontents` itself. - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Formerly, the meaning of :code-tex:`\\tableofcontents` was modified by Sphinx. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Hard-coded redefinitions of :code-tex:`\\l@section` and :code-tex:`\\l@subsection` formerly done during loading of ``'manual'`` docclass are now executed later via @@ -1706,7 +1706,7 @@ Macros Defined in the class files :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`. - .. versionchanged:: 1.8.3 + .. version-changed:: 1.8.3 Formerly, :code-tex:`\\maketitle` from LaTeX document class was modified by Sphinx. @@ -1716,7 +1716,7 @@ Macros the ``'preamble'`` key of :confval:`latex_elements` to add a custom definition of :code-tex:`\\sphinxbackoftitlepage`. - .. versionadded:: 1.8.3 + .. version-added:: 1.8.3 - :code-tex:`\\sphinxcite`: A wrapper of standard :code-tex:`\\cite` for citation references. @@ -1727,7 +1727,7 @@ Macros The :code-tex:`\\sphinxbox` command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 6.2.0 +.. version-added:: 6.2.0 The :code-tex:`\\sphinxbox[key=value,...]{inline text}` command can be used to "box" inline text elements with all the customizability which has been described in @@ -1817,7 +1817,7 @@ Environments elements: they are rendered in a ``sphinxlegend`` environment. The default definition issues :code-tex:`\\small`, and ends with :code-tex:`\\par`. - .. versionadded:: 1.5.6 + .. version-added:: 1.5.6 Formerly, the :code-tex:`\\small` was hardcoded in LaTeX writer and the ending :code-tex:`\\par` was lacking. @@ -1841,7 +1841,7 @@ Environments environments, configured to use the parameters (colors, border thickness) specific to each type, which can be set via ``'sphinxsetup'`` string. - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Use of public environment names, separate customizability of the parameters, such as ``noteBorderColor``, ``noteborder``, ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ... @@ -1850,8 +1850,8 @@ Environments It takes one argument which will be the localized string ``See also`` followed with a colon. - .. versionadded:: 6.1.0 - .. versionchanged:: 6.2.0 + .. version-added:: 6.1.0 + .. version-changed:: 6.2.0 Colon made part of the mark-up rather than being inserted by the environment for coherence with how admonitions are handled generally. @@ -1860,19 +1860,19 @@ Environments (with a colon at the end; the default rendering will remove that colon and put the localized string in its own colored title-row). - .. versionadded:: 7.4.0 + .. version-added:: 7.4.0 - The :dudir:`topic`, contents_ and :dudir:`sidebar` directives are associated with respectively ``sphinxtopic``, ``sphinxcontents``, and ``sphinxsidebar`` environments. - .. versionadded:: 1.4.2 + .. version-added:: 1.4.2 Former code refactored into an environment allowing page breaks. - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Options ``shadowsep``, ``shadowsize``, ``shadowrule``. - .. versionadded:: 8.1.0 + .. version-added:: 8.1.0 Separate environments (all three wrappers around ``sphinxShadowBox``) and separate customizability. @@ -1885,19 +1885,19 @@ Environments environment is ``sphinxVerbatimintable`` (it does not draw a frame, but allows a caption). - .. versionchanged:: 1.5 + .. version-changed:: 1.5 ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used inside tables. - .. versionadded:: 1.5 + .. version-added:: 1.5 Options ``verbatimwithframe``, ``verbatimwrapslines``, ``verbatimsep``, ``verbatimborder``. - .. versionadded:: 1.6.6 + .. version-added:: 1.6.6 Support for ``:emphasize-lines:`` option - .. versionadded:: 1.6.6 + .. version-added:: 1.6.6 Easier customizability of the formatting via exposed to user LaTeX macros such as :code-tex:`\\sphinxVerbatimHighlightLine`. @@ -1906,7 +1906,7 @@ Environments are wrappers of the ``thebibliography`` and respectively ``theindex`` environments as provided by the document class (or packages). - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Formerly, the original environments were modified by Sphinx. Miscellany @@ -1918,7 +1918,7 @@ Miscellany in a narrow context (like a table cell). For ``'lualatex'`` which does not need the trick, the :code-tex:`\\sphinxAtStartPar` does nothing. - .. versionadded:: 3.5.0 + .. version-added:: 3.5.0 - The section, subsection, ... headings are set using *titlesec*'s :code-tex:`\\titleformat` command. @@ -1928,7 +1928,7 @@ Miscellany :code-tex:`\\ChTitleVar`. File :file:`sphinx.sty` has custom re-definitions in case of *fncychap* option ``Bjarne``. - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Formerly, use of *fncychap* with other styles than ``Bjarne`` was dysfunctional. @@ -1938,7 +1938,7 @@ Miscellany :code-tex:`\\DUrole` for some components, with one or two-letters class names as in HTML output. - .. versionchanged:: 8.1.0 + .. version-changed:: 8.1.0 When multiple classes are injected via a a custom role, the LaTeX output uses nested :code-tex:`\\DUrole`'s as in the `Docutils documentation `_. Formerly it used a single :code-tex:`\\DUrole` with @@ -1960,7 +1960,7 @@ Miscellany Currently the class names must contain only ASCII characters and avoid characters special to LaTeX such as ``\``. - .. versionadded:: 4.1.0 + .. version-added:: 4.1.0 .. hint:: @@ -1972,10 +1972,10 @@ Miscellany ``tabular.tex.jinja`` can be added to ``_templates/`` to configure some aspects of table rendering (such as the caption position). - .. versionadded:: 1.6 + .. version-added:: 1.6 currently all template variables are unstable and undocumented. - .. versionchanged:: 7.4 + .. version-changed:: 7.4 Added support for the ``.jinja`` file extension, which is preferred. The old file names remain supported. (``latex.tex_t``, ``longtable.tex_t``, ``tabulary.tex_t``, and ``tabular.tex_t``) diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst index 8eafcd9e274..2851b848a9a 100644 --- a/doc/man/sphinx-apidoc.rst +++ b/doc/man/sphinx-apidoc.rst @@ -88,7 +88,7 @@ Options Put documentation for each module on its own page. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. option:: -E, --no-headings @@ -99,7 +99,7 @@ Options Include "_private" modules. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. option:: --implicit-namespaces @@ -140,7 +140,7 @@ These options are used when :option:`--full` is specified: .. rubric:: Project templating -.. versionadded:: 2.2 +.. version-added:: 2.2 Project templating options for sphinx-apidoc .. option:: -t, --templatedir=TEMPLATEDIR diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 055e3f366cc..e3efe3a6276 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -66,7 +66,7 @@ Options * doctrees are saved to ``/doctrees`` * output files are saved to ``/`` - .. versionadded:: 1.2.1 + .. version-added:: 1.2.1 .. option:: -b buildername, --builder buildername @@ -75,7 +75,7 @@ Options See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders. Extensions can add their own builders. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--builder`` long option. .. option:: -a, --write-all @@ -88,7 +88,7 @@ Options To read and re-process every file, use :option:`--fresh-env` instead. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--write-all`` long option. .. option:: -E, --fresh-env @@ -97,7 +97,7 @@ Options cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--fresh-env`` long option. .. option:: -t tag, --tag tag @@ -107,9 +107,9 @@ Options include their content only if certain tags are set. See :ref:`including content based on tags ` for further detail. - .. versionadded:: 0.6 + .. version-added:: 0.6 - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--tag`` long option. .. option:: -d path, --doctree-dir path @@ -120,7 +120,7 @@ Options the build directory; with this option you can select a different cache directory (the doctrees can be shared between all builders). - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--doctree-dir`` long option. .. option:: -j N, --jobs N @@ -132,13 +132,13 @@ Options If ``auto`` argument is given, Sphinx uses the number of CPUs as *N*. Defaults to 1. - .. versionadded:: 1.2 + .. version-added:: 1.2 This option should be considered *experimental*. - .. versionchanged:: 1.7 + .. version-changed:: 1.7 Support ``auto`` argument. - .. versionchanged:: 6.2 + .. version-changed:: 6.2 Add ``--jobs`` long option. .. option:: -c path, --conf-dir path @@ -149,18 +149,18 @@ Options configuration directory, so they will have to be present at this location too. - .. versionadded:: 0.3 + .. version-added:: 0.3 - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--conf-dir`` long option. .. option:: -C, --isolated Don't look for a configuration file; only take options via the :option:`--define` option. - .. versionadded:: 0.5 + .. version-added:: 0.5 - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--isolated`` long option. .. option:: -D setting=value, --define setting=value @@ -176,22 +176,22 @@ Options For boolean values, use ``0`` or ``1`` as the value. - .. versionchanged:: 0.6 + .. version-changed:: 0.6 The value can now be a dictionary value. - .. versionchanged:: 1.3 + .. version-changed:: 1.3 The value can now also be a list value. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--define`` long option. .. option:: -A name=value, --html-define name=value Make the *name* assigned to *value* in the HTML templates. - .. versionadded:: 0.5 + .. version-added:: 0.5 - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--html-define`` long option. .. option:: -n, --nitpicky @@ -200,30 +200,30 @@ Options references. See the config value :confval:`nitpick_ignore` for a way to exclude some references as "known missing". - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--nitpicky`` long option. .. option:: -N, --no-color Do not emit colored output. - .. versionchanged:: 1.6 + .. version-changed:: 1.6 Add ``--no-color`` long option. .. option:: --color Emit colored output. Auto-detected by default. - .. versionadded:: 1.6 + .. version-added:: 1.6 .. option:: -v, --verbose Increase verbosity (log-level). This option can be given up to three times to get more debug logging output. It implies :option:`-T`. - .. versionadded:: 1.2 + .. version-added:: 1.2 - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--verbose`` long option. .. option:: -q, --quiet @@ -231,7 +231,7 @@ Options Do not output anything on standard output, only write warnings and errors to standard error. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--quiet`` long option. .. option:: -Q, --silent @@ -239,18 +239,18 @@ Options Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--silent`` long option. .. option:: -w file, --warning-file file Write warnings (and errors) to the given file, in addition to standard error. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 ANSI control sequences are stripped when writing to *file*. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--warning-file`` long option. .. option:: -W, --fail-on-warning @@ -259,9 +259,9 @@ Options This means that :program:`sphinx-build` exits with exit status 1 if any warnings are generated during the build. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--fail-on-warning`` long option. - .. versionchanged:: 8.1 + .. version-changed:: 8.1 :program:`sphinx-build` no longer exits on the first warning, but instead runs the entire build and exits with exit status 1 if any warnings were generated. @@ -275,8 +275,8 @@ Options Using :option:`!--keep-going` runs :program:`sphinx-build` to completion and exits with exit status 1 if errors are encountered. - .. versionadded:: 1.8 - .. versionchanged:: 8.1 + .. version-added:: 1.8 + .. version-changed:: 8.1 :program:`sphinx-build` no longer exits on the first warning, meaning that in effect :option:`!--keep-going` is always enabled. The option is retained for compatibility, but may be removed at some @@ -291,9 +291,9 @@ Options only a summary is displayed and the traceback information is saved to a file for further analysis. - .. versionadded:: 1.2 + .. version-added:: 1.2 - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--show-traceback`` long option. .. option:: -P, --pdb @@ -301,7 +301,7 @@ Options (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an unhandled exception occurs while building. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Add ``--pdb`` long option. .. option:: --exception-on-warning @@ -309,13 +309,13 @@ Options Raise an exception when a warning is emitted during the build. This can be useful in combination with :option:`--pdb` to debug warnings. - .. versionadded:: 8.1 + .. version-added:: 8.1 .. option:: -h, --help, --version Display usage summary or Sphinx version. - .. versionadded:: 1.2 + .. version-added:: 1.2 You can also give one or more filenames on the command line after the source and build directories. Sphinx will then try to build only these output files @@ -374,14 +374,14 @@ variables to customize behavior: `no-color.org `__ for other libraries supporting this community standard. - .. versionadded:: 4.5.0 + .. version-added:: 4.5.0 .. describe:: FORCE_COLOR When set (regardless of value), :program:`sphinx-build` will use color in terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``. - .. versionadded:: 4.5.0 + .. version-added:: 4.5.0 .. _when-deprecation-warnings-are-displayed: diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst index ea473e81eb7..9f4c194b9a8 100644 --- a/doc/man/sphinx-quickstart.rst +++ b/doc/man/sphinx-quickstart.rst @@ -127,10 +127,10 @@ Options :file:`Makefile/make.bat` uses (or doesn't use) :ref:`make-mode `. Default is ``use``, which generates a more concise :file:`Makefile/make.bat`. - .. versionchanged:: 1.5 + .. version-changed:: 1.5 make-mode is default. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Support for disabling the make-mode will be removed in Sphinx 8. .. versionremoved:: 8.0 @@ -147,7 +147,7 @@ Options .. rubric:: Project templating -.. versionadded:: 1.5 +.. version-added:: 1.5 Project templating options for sphinx-quickstart .. option:: -t, --templatedir=TEMPLATEDIR diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst index 4d52c34debe..e3802bcb43a 100644 --- a/doc/usage/advanced/intl.rst +++ b/doc/usage/advanced/intl.rst @@ -3,7 +3,7 @@ Internationalization ==================== -.. versionadded:: 1.1 +.. version-added:: 1.1 Complementary to translations provided for Sphinx-generated messages such as navigation bars, Sphinx provides mechanisms facilitating the translation of @@ -82,7 +82,7 @@ this:: text. This does not apply to code blocks, where ``#noqa`` is ignored because code blocks do not contain references anyway.) -.. versionadded:: 4.5 +.. version-added:: 4.5 The ``#noqa`` mechanism. @@ -196,7 +196,7 @@ section describe an easy way to translate with *sphinx-intl*. Congratulations! You got the translated documentation in the ``_build/html`` directory. -.. versionadded:: 1.3 +.. version-added:: 1.3 :program:`sphinx-build` that is invoked by make command will build po files into mo files. @@ -390,7 +390,7 @@ https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator Translation progress and statistics ----------------------------------- -.. versionadded:: 7.1.0 +.. version-added:: 7.1.0 During the rendering process, Sphinx marks each translatable node with a ``translated`` attribute, diff --git a/doc/usage/advanced/websupport/api.rst b/doc/usage/advanced/websupport/api.rst index c657433f009..cdeb85fcab0 100644 --- a/doc/usage/advanced/websupport/api.rst +++ b/doc/usage/advanced/websupport/api.rst @@ -57,7 +57,7 @@ The WebSupport class should be a string specifying that path (e.g. ``'docs'``). -.. versionchanged:: 1.6 +.. version-changed:: 1.6 WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport. Please add ``sphinxcontrib-websupport`` package in your dependency and use diff --git a/doc/usage/advanced/websupport/index.rst b/doc/usage/advanced/websupport/index.rst index 08166405196..5704e8e1eed 100644 --- a/doc/usage/advanced/websupport/index.rst +++ b/doc/usage/advanced/websupport/index.rst @@ -3,7 +3,7 @@ Sphinx Web Support ================== -.. versionadded:: 1.1 +.. version-added:: 1.1 Sphinx provides a Python API to easily integrate Sphinx documentation into your web application. To learn more read the :ref:`websupportquickstart`. diff --git a/doc/usage/advanced/websupport/searchadapters.rst b/doc/usage/advanced/websupport/searchadapters.rst index d8e1adcb52d..2e489faf098 100644 --- a/doc/usage/advanced/websupport/searchadapters.rst +++ b/doc/usage/advanced/websupport/searchadapters.rst @@ -21,7 +21,7 @@ documentation of the :class:`BaseSearch` class below. Defines an interface for search adapters. -.. versionchanged:: 1.6 +.. version-changed:: 1.6 BaseSearch class is moved to sphinxcontrib.websupport.search from sphinx.websupport.search. diff --git a/doc/usage/advanced/websupport/storagebackends.rst b/doc/usage/advanced/websupport/storagebackends.rst index 9ba14806608..1f56d328144 100644 --- a/doc/usage/advanced/websupport/storagebackends.rst +++ b/doc/usage/advanced/websupport/storagebackends.rst @@ -21,7 +21,7 @@ documentation of the :class:`StorageBackend` class below. Defines an interface for storage backends. -.. versionchanged:: 1.6 +.. version-changed:: 1.6 StorageBackend class is moved to sphinxcontrib.websupport.storage from sphinx.websupport.storage. diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index e293399282e..bdd14389905 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -97,7 +97,7 @@ The most common builders are: .. autoattribute:: supported_image_types - .. versionadded:: 0.6 + .. version-added:: 0.6 .. module:: sphinx.builders.singlehtml .. class:: SingleFileHTMLBuilder @@ -112,7 +112,7 @@ The most common builders are: .. autoattribute:: supported_image_types - .. versionadded:: 1.0 + .. version-added:: 1.0 .. module:: sphinxcontrib.htmlhelp .. class:: HTMLHelpBuilder @@ -134,7 +134,7 @@ The most common builders are: also generates `Qt help`_ collection support files that allow the Qt collection generator to compile them. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Moved to sphinxcontrib.qthelp from sphinx.builders package. @@ -170,9 +170,9 @@ The most common builders are: .. autoattribute:: supported_image_types - .. versionadded:: 1.3 + .. version-added:: 1.3 - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Moved to sphinxcontrib.applehelp from sphinx.builders package. @@ -189,7 +189,7 @@ The most common builders are: .. autoattribute:: supported_image_types - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Moved to sphinxcontrib.devhelp from sphinx.builders package. @@ -208,9 +208,9 @@ The most common builders are: .. autoattribute:: supported_image_types - .. versionadded:: 1.4 + .. version-added:: 1.4 - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Since Sphinx 1.5, the epub3 builder is used as the default epub builder. @@ -243,10 +243,10 @@ The most common builders are: * ``texlive-latex-extra`` * ``latexmk`` - .. versionchanged:: 4.0.0 + .. version-changed:: 4.0.0 TeX Gyre fonts now required for ``'pdflatex'`` engine (default). - .. versionchanged:: 7.4.0 + .. version-changed:: 7.4.0 LaTeX package ``xcolor`` is now required (it is part of Ubuntu ``texlive-latex-recommended`` anyhow). The LaTeX package ``fontawesome5`` is recommended. See the :ref:`'sphinxsetup' @@ -316,7 +316,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionadded:: 0.4 + .. version-added:: 0.4 .. module:: sphinx.builders.manpage .. class:: ManualPageBuilder @@ -331,7 +331,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionadded:: 1.0 + .. version-added:: 1.0 .. module:: sphinx.builders.texinfo @@ -354,7 +354,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionadded:: 1.1 + .. version-added:: 1.1 .. currentmodule:: sphinxcontrib.serializinghtml @@ -401,7 +401,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. See :ref:`serialization-details` for details about the output format. - .. versionadded:: 0.5 + .. version-added:: 0.5 .. class:: PickleHTMLBuilder @@ -439,7 +439,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. The file suffix is ``.fjson``. The global context is called ``globalcontext.json``, the search index ``searchindex.json``. - .. versionadded:: 0.5 + .. version-added:: 0.5 .. module:: sphinx.builders.gettext .. class:: MessageCatalogBuilder @@ -455,13 +455,13 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionadded:: 1.1 + .. version-added:: 1.1 .. module:: sphinx.builders.changes .. class:: ChangesBuilder - This builder produces an HTML overview of all :rst:dir:`versionadded`, - :rst:dir:`versionchanged`, :rst:dir:`deprecated` and :rst:dir:`versionremoved` + This builder produces an HTML overview of all :rst:dir:`version-added`, + :rst:dir:`version-changed`, :rst:dir:`deprecated` and :rst:dir:`versionremoved` directives for the current :confval:`version`. This is useful to generate a changelog file, for example. @@ -481,7 +481,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionadded:: 1.4 + .. version-added:: 1.4 .. module:: sphinx.builders.linkcheck .. class:: CheckExternalLinksBuilder @@ -496,11 +496,11 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Since Sphinx 1.5, the linkcheck builder uses the requests module. - .. versionchanged:: 3.4 + .. version-changed:: 3.4 The linkcheck builder retries links when servers apply rate limits. @@ -517,7 +517,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionadded:: 1.2 + .. version-added:: 1.2 .. class:: PseudoXMLBuilder @@ -533,7 +533,7 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. autoattribute:: supported_image_types - .. versionadded:: 1.2 + .. version-added:: 1.2 Built-in Sphinx extensions that offer more builders are: diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 981b386bb7c..637320993cc 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -138,14 +138,14 @@ Project information * :code-py:`copyright = '%Y, Author Name'` * :code-py:`copyright = 'YYYY-%Y, Author Name'` - .. versionadded:: 3.5 + .. version-added:: 3.5 The :code-py:`project_copyright` alias. - .. versionchanged:: 7.1 + .. version-changed:: 7.1 The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line. - .. versionchanged:: 8.1 + .. version-changed:: 8.1 Copyright statements support the :code-py:`'%Y'` placeholder. .. confval:: version @@ -191,9 +191,9 @@ General configuration if the running version of Sphinx is too old. By default, there is no minimum version. - .. versionadded:: 1.0 + .. version-added:: 1.0 - .. versionchanged:: 1.4 + .. version-changed:: 1.4 Allow a ``'major.minor.micro'`` version string. .. confval:: extensions @@ -267,7 +267,7 @@ General configuration This requires that the extension declares its version in the :code-py:`setup()` function. See :ref:`dev-extensions` for further details. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. confval:: manpages_url :type: :code-py:`str` @@ -299,7 +299,7 @@ General configuration # To use helpmanual.io: manpages_url = 'https://helpmanual.io/man{section}/{page}' - .. versionadded:: 1.7 + .. version-added:: 1.7 .. confval:: today today_fmt @@ -335,7 +335,7 @@ Options for figure numbering The LaTeX builder always assigns numbers whether this option is enabled or not. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. confval:: numfig_format :type: :code-py:`dict[str, str]` @@ -357,7 +357,7 @@ Options for figure numbering 'table': 'Table %s', } - .. versionadded:: 1.3 + .. version-added:: 1.3 .. confval:: numfig_secnum_depth :type: :code-py:`int` @@ -376,9 +376,9 @@ Options for figure numbering and if there is no top-level section, the prefix will not be added. * Any other positive integer can be used, following the rules above. - .. versionadded:: 1.3 + .. version-added:: 1.3 - .. versionchanged:: 1.7 + .. version-changed:: 1.7 The LaTeX builder obeys this setting if :confval:`numfig` is set to :code-py:`True`. @@ -397,9 +397,9 @@ Options for highlighting The value should be a valid Pygments lexer name, see :ref:`code-examples` for more details. - .. versionadded:: 0.5 + .. version-added:: 0.5 - .. versionchanged:: 1.4 + .. version-changed:: 1.4 The default is now :code-py:`'default'`. .. confval:: highlight_options @@ -419,8 +419,8 @@ Options for highlighting 'php': {'startinline': True}, } - .. versionadded:: 1.3 - .. versionchanged:: 3.5 + .. version-added:: 1.3 + .. version-changed:: 3.5 Allow configuring highlight options for multiple lexers. @@ -432,7 +432,7 @@ Options for highlighting If not set, either the theme's default style or :code-py:`'sphinx'` is selected for HTML output. - .. versionchanged:: 0.3 + .. version-changed:: 0.3 If the value is a fully-qualified name of a custom Pygments style class, this is then used as custom style. @@ -446,7 +446,7 @@ Options for HTTP requests If True, Sphinx verifies server certificates. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. confval:: tls_cacerts :type: :code-py:`str | dict[str, str]` @@ -458,7 +458,7 @@ Options for HTTP requests hostnames to the certificate file path. The certificates are used to verify server certifications. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. tip:: @@ -476,7 +476,7 @@ Options for HTTP requests Set the User-Agent used by Sphinx for HTTP requests. - .. versionadded:: 2.3 + .. version-added:: 2.3 .. _intl-options: @@ -504,12 +504,12 @@ See the documentation on :ref:`intl` for details. In the LaTeX builder, a suitable language will be selected as an option for the *Babel* package. - .. versionadded:: 0.5 + .. version-added:: 0.5 - .. versionchanged:: 1.4 + .. version-changed:: 1.4 Support figure substitution - .. versionchanged:: 5.0 + .. version-changed:: 5.0 The default is now :code-py:`'en'` (previously :code-py:`None`). Currently supported languages by Sphinx are: @@ -591,9 +591,9 @@ See the documentation on :ref:`intl` for details. is useful to check the :confval:`!locale_dirs` setting is working as expected. If the message catalog directory not found, debug messages are emitted. - .. versionadded:: 0.5 + .. version-added:: 0.5 - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Use ``locales`` directory as a default value .. confval:: gettext_allow_fuzzy_translations @@ -602,7 +602,7 @@ See the documentation on :ref:`intl` for details. If True, "fuzzy" messages in the message catalogs are used for translation. - .. versionadded:: 4.3 + .. version-added:: 4.3 .. confval:: gettext_compact :type: :code-py:`bool | str` @@ -621,9 +621,9 @@ See the documentation on :ref:`intl` for details. With this option set to :code-py:`False`, it is ``markup/code``. With this option set to :code-py:`'sample'`, it is ``sample``. - .. versionadded:: 1.1 + .. version-added:: 1.1 - .. versionchanged:: 3.3 + .. version-changed:: 3.3 Allow string values. .. confval:: gettext_uuid @@ -645,7 +645,7 @@ See the documentation on :ref:`intl` for details. .. _Levenshtein: https://pypi.org/project/Levenshtein/ - .. versionadded:: 1.3 + .. version-added:: 1.3 .. confval:: gettext_location :type: :code-py:`bool` @@ -654,7 +654,7 @@ See the documentation on :ref:`intl` for details. If :code-py:`True`, Sphinx generates location information for messages in message catalogs. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. confval:: gettext_auto_build :type: :code-py:`bool` @@ -663,7 +663,7 @@ See the documentation on :ref:`intl` for details. If :code-py:`True`, Sphinx builds a ``.mo`` file for each translation catalog file. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. confval:: gettext_additional_targets :type: :code-py:`set[str] | Sequence[str]` @@ -685,10 +685,10 @@ See the documentation on :ref:`intl` for details. * :code-py:`'raw'` -- raw content * :code-py:`'image'` -- image/figure uri - .. versionadded:: 1.3 - .. versionchanged:: 4.0 + .. version-added:: 1.3 + .. version-changed:: 4.0 The alt text for images is translated by default. - .. versionchanged:: 7.4 + .. version-changed:: 7.4 Permit and prefer a set type. .. confval:: figure_language_filename @@ -728,12 +728,12 @@ See the documentation on :ref:`intl` for details. figure_language_filename = '{path}{language}/{basename}{ext}' - .. versionadded:: 1.4 + .. version-added:: 1.4 - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Added ``{path}`` and ``{basename}`` tokens. - .. versionchanged:: 3.2 + .. version-changed:: 3.2 Added ``{docpath}`` token. .. confval:: translation_progress_classes @@ -754,7 +754,7 @@ See the documentation on :ref:`intl` for details. :code-py:`False` Do not add any classes to indicate translation progress. - .. versionadded:: 7.1 + .. version-added:: 7.1 Options for markup @@ -774,7 +774,7 @@ Options for markup The default role can always be set within individual documents using the standard reStructuredText :dudir:`default-role` directive. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. confval:: keep_warnings :type: :code-py:`bool` @@ -784,7 +784,7 @@ Options for markup Warnings are always written to the standard error stream when :program:`sphinx-build` is run, regardless of this setting. - .. versionadded:: 0.5 + .. version-added:: 0.5 .. confval:: option_emphasise_placeholders :type: :code-py:`bool` @@ -795,7 +795,7 @@ Options for markup For example, ``option_emphasise_placeholders=True`` and ``.. option:: -foption={TYPE}`` would render with ``TYPE`` emphasised. - .. versionadded:: 5.1 + .. version-added:: 5.1 .. confval:: primary_domain :type: :code-py:`str` @@ -819,7 +819,7 @@ Options for markup primary_domain = 'cpp' - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: rst_epilog :type: :code-py:`str` @@ -839,7 +839,7 @@ Options for markup .. |psf| replace:: Python Software Foundation """ - .. versionadded:: 0.6 + .. version-added:: 0.6 .. confval:: rst_prolog :type: :code-py:`str` @@ -859,7 +859,7 @@ Options for markup .. |psf| replace:: Python Software Foundation """ - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: show_authors :type: :code-py:`bool` @@ -876,7 +876,7 @@ Options for markup necessary for the reStructuredText parser to recognise the footnote, but do not look too nice in the output. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. _math-options: @@ -895,7 +895,7 @@ These options control maths markup and notation. Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``. - .. versionadded:: 1.7 + .. version-added:: 1.7 .. confval:: math_number_all :type: :code-py:`bool` @@ -908,7 +908,7 @@ These options control maths markup and notation. math_number_all = True - .. versionadded:: 1.4 + .. version-added:: 1.4 .. confval:: math_numfig :type: :code-py:`bool` @@ -920,7 +920,7 @@ These options control maths markup and notation. The :rst:role:`eq`, not :rst:role:`numref`, role must be used to reference equation numbers. - .. versionadded:: 1.7 + .. version-added:: 1.7 .. confval:: math_numsep :type: :code-py:`str` @@ -932,7 +932,7 @@ These options control maths markup and notation. Example: :code-py:`'-'` gets rendered as ``1.2-3``. - .. versionadded:: 7.4 + .. version-added:: 7.4 Options for the nitpicky mode @@ -957,7 +957,7 @@ Options for the nitpicky mode nitpicky = True - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: nitpick_ignore :type: :code-py:`set[tuple[str, str]] | Sequence[tuple[str, str]]` @@ -976,8 +976,8 @@ Options for the nitpicky mode ('envvar', 'LD_LIBRARY_PATH'), } - .. versionadded:: 1.1 - .. versionchanged:: 6.2 + .. version-added:: 1.1 + .. version-changed:: 6.2 Changed allowable container types to a set, list, or tuple .. confval:: nitpick_ignore_regex @@ -996,8 +996,8 @@ Options for the nitpicky mode such as :code-py:`('py:const', 'foo_package.bar.BAZ_VALUE')` or :code-py:`('py:class', 'food.bar.Barman')`. - .. versionadded:: 4.1 - .. versionchanged:: 6.2 + .. version-added:: 4.1 + .. version-changed:: 6.2 Changed allowable container types to a set, list, or tuple @@ -1032,7 +1032,7 @@ Options for object signatures such as seen in the C, C++, and Python domains (e.g. :rst:dir:`py:function:single-line-parameter-list`). - .. versionadded:: 7.1 + .. version-added:: 7.1 .. confval:: strip_signature_backslash :type: :code-py:`bool` @@ -1043,7 +1043,7 @@ Options for object signatures This was the behaviour before version 3.0, and setting this variable to :code-py:`True` will reinstate that behaviour. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. confval:: toc_object_entries :type: :code-py:`bool` @@ -1052,7 +1052,7 @@ Options for object signatures Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.). - .. versionadded:: 5.2 + .. version-added:: 5.2 .. confval:: toc_object_entries_show_parents :type: :code-py:`'domain' | 'hide' | 'all'` @@ -1074,7 +1074,7 @@ Options for object signatures Use :code-py:`'all'` to show the fully-qualified name for the object (i.e. :code-py:`module.Class.method()`), displaying all parents. - .. versionadded:: 5.2 + .. version-added:: 5.2 Options for source files @@ -1103,7 +1103,7 @@ Options for source files :confval:`exclude_patterns` is also consulted when looking for static files in :confval:`html_static_path` and :confval:`html_extra_path`. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: include_patterns :type: :code-py:`Sequence[str]` @@ -1126,7 +1126,7 @@ Options for source files * :code-py:`'**/doc'` -- all ``doc`` directories (this might be useful if documentation is co-located with source files) - .. versionadded:: 5.1 + .. version-added:: 5.1 .. confval:: master_doc root_doc @@ -1143,10 +1143,10 @@ Options for source files master_doc = 'contents' - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Default is :code-py:`'index'` (previously :code-py:`'contents'`). - .. versionadded:: 4.0 + .. version-added:: 4.0 The :confval:`!root_doc` alias. .. confval:: source_encoding @@ -1156,7 +1156,7 @@ Options for source files The file encoding of all source files. The recommended encoding is ``'utf-8-sig'``. - .. versionadded:: 0.5 + .. version-added:: 0.5 .. version-deprecated:: 8.3 Support for source encodings other than UTF-8 is deprecated. Sphinx 10 will only support UTF-8 files. @@ -1191,10 +1191,10 @@ Options for source files .. note:: File extensions must begin with a dot (``'.'``). - .. versionchanged:: 1.3 + .. version-changed:: 1.3 Support a list of file extensions. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Change to a map of file extensions to file types. @@ -1211,7 +1211,7 @@ Options for smart quotes __ https://docutils.sourceforge.io/docs/user/smartquotes.html - .. versionadded:: 1.6.6 + .. version-added:: 1.6.6 Replaces the now-removed :confval:`!html_use_smartypants`. It applies by default to all builders except ``man`` and ``text`` (see :confval:`smartquotes_excludes`.) @@ -1259,7 +1259,7 @@ Options for smart quotes :code-py:`'w'` Convert ``'"'`` entities to ``'"'`` - .. versionadded:: 1.6.6 + .. version-added:: 1.6.6 .. confval:: smartquotes_excludes :type: :code-py:`dict[str, list[str]]` @@ -1305,7 +1305,7 @@ Options for smart quotes This can follow some ``make html`` with no problem, in contrast to the situation from the prior note. - .. versionadded:: 1.6.6 + .. version-added:: 1.6.6 Options for templating @@ -1340,7 +1340,7 @@ Options for templating templates_path = ['.templates'] - .. versionchanged:: 1.3 + .. version-changed:: 1.3 As these files are not meant to be built, they are automatically excluded when discovering source files. @@ -1357,8 +1357,8 @@ Options for warning control This setting can be useful for determining which warnings types to include in a :confval:`suppress_warnings` list. - .. versionadded:: 7.3.0 - .. versionchanged:: 8.0.0 + .. version-added:: 7.3.0 + .. version-changed:: 8.0.0 The default is now :code-py:`True`. .. confval:: suppress_warnings @@ -1367,7 +1367,7 @@ Options for warning control A list of warning codes to suppress arbitrary warning messages. - .. versionadded:: 1.4 + .. version-added:: 1.4 By default, Sphinx supports the following warning codes: @@ -1424,60 +1424,60 @@ Options for warning control You can choose from these types. You can also give only the first component to exclude all warnings attached to it. - .. versionadded:: 1.4 + .. version-added:: 1.4 ``ref.citation``, ``ref.doc``, ``ref.keyword``, ``ref.numref``, ``ref.option``, ``ref.ref``, and ``ref.term``. - .. versionadded:: 1.4.2 + .. version-added:: 1.4.2 ``app.add_directive``, ``app.add_generic_role``, ``app.add_node``, ``app.add_role``, and ``app.add_source_parser``. - .. versionadded:: 1.5 + .. version-added:: 1.5 ``misc.highlighting_failure``. - .. versionadded:: 1.5.1 + .. version-added:: 1.5.1 ``epub.unknown_project_files``. - .. versionadded:: 1.5.2 + .. version-added:: 1.5.2 ``toc.secnum``. - .. versionadded:: 1.6 + .. version-added:: 1.6 ``ref.footnote``, ``download.not_readable``, and ``image.not_readable``. - .. versionadded:: 1.7 + .. version-added:: 1.7 ``ref.python``. - .. versionadded:: 2.0 + .. version-added:: 2.0 ``autodoc.import_object``. - .. versionadded:: 2.1 + .. version-added:: 2.1 ``autosectionlabel.``. - .. versionadded:: 3.1 + .. version-added:: 3.1 ``toc.circular``. - .. versionadded:: 3.3 + .. version-added:: 3.3 ``epub.duplicated_toc_entry``. - .. versionadded:: 4.3 + .. version-added:: 4.3 ``toc.excluded`` and ``toc.not_readable``. - .. versionadded:: 4.5 + .. version-added:: 4.5 ``i18n.inconsistent_references``. - .. versionadded:: 7.1 + .. version-added:: 7.1 ``index``. - .. versionadded:: 7.3 + .. version-added:: 7.3 ``config.cache``, ``intersphinx.external``, and ``toc.no_title``. - .. versionadded:: 7.4 + .. version-added:: 7.4 ``docutils`` and ``autosummary.import_cycle``. - .. versionadded:: 8.0 + .. version-added:: 8.0 ``misc.copy_overwrite``. - .. versionadded:: 8.2 + .. version-added:: 8.2 ``autodoc.mocked_object``, ``duplicate_declaration.c``, ``duplicate_declaration.cpp``, ``i18n.babel``, ``i18n.not_readable``, ``i18n.not_writeable``, @@ -1505,8 +1505,8 @@ and also make use of these options. The theme for HTML output. See the :doc:`HTML theming section `. - .. versionadded:: 0.6 - .. versionchanged:: 1.3 + .. version-added:: 0.6 + .. version-changed:: 1.3 The default theme is now :code-py:`'alabaster'`. .. confval:: html_theme_options @@ -1519,7 +1519,7 @@ and also make use of these options. The options understood by the :ref:`builtin themes ` are described :ref:`here `. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. confval:: html_theme_path :type: :code-py:`list[str]` @@ -1529,7 +1529,7 @@ and also make use of these options. either as subdirectories or as zip files. Relative paths are taken as relative to the :term:`configuration directory`. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. confval:: html_style :type: :code-py:`Sequence[str] | str` @@ -1542,7 +1542,7 @@ and also make use of these options. If you only want to add or override a few things from the theme, use CSS ``@import`` to import the theme's stylesheet. - .. versionchanged:: 5.1 + .. version-changed:: 5.1 The value can be a iterable of strings. .. confval:: html_title @@ -1560,7 +1560,7 @@ and also make use of these options. A shorter "title" for HTML documentation. This is used for links in the header and in the HTML Help documentation. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. confval:: html_baseurl :type: :code-py:`str` @@ -1570,7 +1570,7 @@ and also make use of these options. It is used to indicate the location of document using :rfc:`the Canonical Link Relation <6596>`. - .. versionadded:: 1.8 + .. version-added:: 1.8 .. confval:: html_codeblock_linenos_style :type: :code-py:`'inline' | 'table'` @@ -1583,8 +1583,8 @@ and also make use of these options. :code-py:`'inline'` Display line numbers using ```` tag - .. versionadded:: 3.2 - .. versionchanged:: 4.0 + .. version-added:: 3.2 + .. version-changed:: 4.0 It defaults to :code-py:`'inline'`. .. version-deprecated:: 4.0 @@ -1598,7 +1598,7 @@ and also make use of these options. :program:`sphinx-build`'s :option:`--html-define ` command-line option. - .. versionadded:: 0.5 + .. version-added:: 0.5 .. confval:: html_logo :type: :code-py:`str` @@ -1611,10 +1611,10 @@ and also make use of these options. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. - .. versionadded:: 0.4.1 + .. version-added:: 0.4.1 The image file will be copied to the ``_static`` directory, but only if the file does not already exist there. - .. versionchanged:: 4.0 + .. version-changed:: 4.0 Also accepts a URL. .. confval:: html_favicon @@ -1638,11 +1638,11 @@ and also make use of these options. html_favicon = 'static/favicon.png' - .. versionadded:: 0.4 + .. version-added:: 0.4 The image file will be copied to the ``_static``, but only if the file does not already exist there. - .. versionchanged:: 4.0 + .. version-changed:: 4.0 Also accepts the URL for the favicon. .. confval:: html_css_files @@ -1670,8 +1670,8 @@ and also make use of these options. to load the CSS file at an earlier or later step. For more information, refer to :meth:`.Sphinx.add_css_file`. - .. versionadded:: 1.8 - .. versionchanged:: 3.5 + .. version-added:: 1.8 + .. version-changed:: 3.5 Support the *priority* attribute .. confval:: html_js_files @@ -1699,8 +1699,8 @@ and also make use of these options. to load the JavaScript file at an earlier or later step. For more information, refer to :meth:`.Sphinx.add_js_file`. - .. versionadded:: 1.8 - .. versionchanged:: 3.5 + .. version-added:: 1.8 + .. version-changed:: 3.5 Support the *priority* attribute .. confval:: html_static_path @@ -1732,13 +1732,13 @@ and also make use of these options. An alternative approach is to use :confval:`html_extra_path`, which allows copying dotfiles under the directories. - .. versionchanged:: 0.4 + .. version-changed:: 0.4 The paths in :confval:`html_static_path` can now contain subdirectories. - .. versionchanged:: 1.0 + .. version-changed:: 1.0 The entries in :confval:`html_static_path` can now be single files. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 The files under :confval:`html_static_path` are excluded from source files. @@ -1756,9 +1756,9 @@ and also make use of these options. As these files are not meant to be built, they are automatically excluded from source files. - .. versionadded:: 1.2 + .. version-added:: 1.2 - .. versionchanged:: 1.4 + .. version-changed:: 1.4 The dotfiles in the extra directory will be copied to the output directory. And it refers :confval:`exclude_patterns` on copying extra @@ -1787,7 +1787,7 @@ and also make use of these options. Add link anchors for each heading and description environment. - .. versionadded:: 3.5 + .. version-added:: 3.5 .. confval:: html_permalinks_icon :type: :code-py:`str` @@ -1796,7 +1796,7 @@ and also make use of these options. Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed. - .. versionadded:: 3.5 + .. version-added:: 3.5 .. confval:: html_sidebars :type: :code-py:`dict[str, Sequence[str]]` @@ -1850,13 +1850,13 @@ and also make use of these options. the chosen theme does not possess a sidebar, like the builtin **scrolls** and **haiku** themes. - .. versionadded:: 1.0 + .. version-added:: 1.0 The ability to use globbing keys and to specify multiple sidebars. .. version-deprecated:: 1.7 A single string value for :confval:`!html_sidebars` will be removed. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 :confval:`!html_sidebars` must be a list of strings, and no longer accepts a single string value. @@ -1897,8 +1897,8 @@ and also make use of these options. 'py-modindex', } - .. versionadded:: 1.0 - .. versionchanged:: 7.4 + .. version-added:: 1.0 + .. version-changed:: 7.4 Permit and prefer a set type. .. confval:: html_use_index @@ -1907,7 +1907,7 @@ and also make use of these options. Controls if an index is added to the HTML documents. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. confval:: html_split_index :type: :code-py:`bool` @@ -1917,7 +1917,7 @@ and also make use of these options. once as a single page with all the entries, and once as one page per starting letter. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. confval:: html_copy_source :type: :code-py:`bool` @@ -1933,7 +1933,7 @@ and also make use of these options. If True (and :confval:`html_copy_source` is true as well), links to the reStructuredText sources will be added to the sidebar. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. confval:: html_sourcelink_suffix :type: :code-py:`str` @@ -1943,7 +1943,7 @@ and also make use of these options. (see :confval:`html_show_sourcelink`), unless files they have this suffix already. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. confval:: html_use_opensearch :type: :code-py:`str` @@ -1957,7 +1957,7 @@ and also make use of these options. from which these documents are served (without trailing slash), e.g. :code-py:`'https://docs.python.org'`. - .. versionadded:: 0.2 + .. version-added:: 0.2 .. confval:: html_file_suffix :type: :code-py:`str` @@ -1965,7 +1965,7 @@ and also make use of these options. The file name suffix (file extension) for generated HTML files. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. confval:: html_link_suffix :type: :code-py:`str` @@ -1974,7 +1974,7 @@ and also make use of these options. The suffix for generated links to HTML files. Intended to support more esoteric server setups. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. confval:: html_show_copyright :type: :code-py:`bool` @@ -1983,7 +1983,7 @@ and also make use of these options. If True, "© Copyright ..." is shown in the HTML footer, with the value or values from :confval:`copyright`. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: html_show_search_summary :type: :code-py:`bool` @@ -1991,7 +1991,7 @@ and also make use of these options. Show a summary of the search result, i.e., the text around the keyword. - .. versionadded:: 4.5 + .. version-added:: 4.5 .. confval:: html_show_sphinx :type: :code-py:`bool` @@ -2001,7 +2001,7 @@ and also make use of these options. .. _Sphinx: https://www.sphinx-doc.org/ - .. versionadded:: 0.4 + .. version-added:: 0.4 .. confval:: html_output_encoding :type: :code-py:`str` @@ -2011,7 +2011,7 @@ and also make use of these options. This encoding name must both be a valid Python encoding name and a valid HTML ``charset`` value. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: html_compact_lists :type: :code-py:`bool` @@ -2022,7 +2022,7 @@ and also make use of these options. ``

`` element for any of its items. This is standard docutils behaviour. Default: :code-py:`True`. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: html_secnumber_suffix :type: :code-py:`str` @@ -2031,7 +2031,7 @@ and also make use of these options. Suffix for section numbers in HTML output. Set to :code-py:`' '` to suppress the final dot on section numbers. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: html_search_language :type: :code-py:`str` @@ -2072,10 +2072,10 @@ and also make use of these options. .. _PyStemmer: https://pypi.org/project/PyStemmer/ - .. versionadded:: 1.1 + .. version-added:: 1.1 Support English (``en``) and Japanese (``ja``). - .. versionchanged:: 1.3 + .. version-changed:: 1.3 Added additional languages. .. confval:: html_search_options @@ -2141,9 +2141,9 @@ and also make use of these options. ``dict`` The ``jieba`` dictionary path for using a custom dictionary. - .. versionadded:: 1.1 + .. version-added:: 1.1 - .. versionchanged:: 1.4 + .. version-changed:: 1.4 Allow any custom splitter in the *type* setting for Japanese. .. confval:: html_search_scorer @@ -2192,7 +2192,7 @@ and also make use of these options. partialTerm: 2, }; - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: html_scaled_image_link :type: :code-py:`bool` @@ -2215,9 +2215,9 @@ and also make use of these options. :scale: 50% :class: no-scaled-link - .. versionadded:: 1.3 + .. version-added:: 1.3 - .. versionchanged:: 3.0 + .. version-changed:: 3.0 Images with the ``no-scaled-link`` class will not be linked. .. confval:: html_math_renderer @@ -2228,7 +2228,7 @@ and also make use of these options. The bundled renders are *mathjax* and *imgmath*. You must also load the relevant extension in :confval:`extensions`. - .. versionadded:: 1.8 + .. version-added:: 1.8 Options for Single HTML output @@ -2273,7 +2273,7 @@ so the HTML options also apply where appropriate. This is the file name suffix for generated HTML help files. - .. versionadded:: 2.0 + .. version-added:: 2.0 .. confval:: htmlhelp_link_suffix :type: :code-py:`str` @@ -2281,7 +2281,7 @@ so the HTML options also apply where appropriate. Suffix for generated links to HTML files. - .. versionadded:: 2.0 + .. version-added:: 2.0 .. _applehelp-options: @@ -2289,7 +2289,7 @@ so the HTML options also apply where appropriate. Options for Apple Help output ----------------------------- -.. versionadded:: 1.3 +.. version-added:: 1.3 These options influence Apple Help output. This builder derives from the HTML builder, @@ -2523,7 +2523,7 @@ so the HTML options also apply where appropriate. The options understood by the :ref:`builtin themes ` are described :ref:`here `. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: epub_title :type: :code-py:`str` @@ -2531,7 +2531,7 @@ so the HTML options also apply where appropriate. The title of the document. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 It defaults to the :confval:`!project` option (previously :confval:`!html_title`). @@ -2541,9 +2541,9 @@ so the HTML options also apply where appropriate. The description of the document. - .. versionadded:: 1.4 + .. version-added:: 1.4 - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Renamed from :confval:`!epub3_description` .. confval:: epub_author @@ -2560,9 +2560,9 @@ so the HTML options also apply where appropriate. The name of a person, organisation, etc. that played a secondary role in the creation of the content of an EPUB Publication. - .. versionadded:: 1.4 + .. version-added:: 1.4 - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Renamed from :confval:`!epub3_contributor` .. confval:: epub_language @@ -2636,7 +2636,7 @@ so the HTML options also apply where appropriate. epub_cover = ('_static/cover.png', '') epub_cover = () - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: epub_css_files :type: :code-py:`Sequence[str | tuple[str, dict[str, str]]]` @@ -2650,7 +2650,7 @@ so the HTML options also apply where appropriate. The *attributes* dictionary is used for the ```` tag's attributes. For more information, see :confval:`html_css_files`. - .. versionadded:: 1.8 + .. version-added:: 1.8 .. confval:: epub_guide :type: :code-py:`Sequence[tuple[str, str, str]]` @@ -2746,7 +2746,7 @@ so the HTML options also apply where appropriate. :code-py:`'includehidden'` Include all ToC entries - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: epub_fix_images :type: :code-py:`bool` @@ -2760,7 +2760,7 @@ so the HTML options also apply where appropriate. .. _Pillow: https://pypi.org/project/Pillow/ - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: epub_max_image_width :type: :code-py:`int` @@ -2774,7 +2774,7 @@ so the HTML options also apply where appropriate. .. _Pillow: https://pypi.org/project/Pillow/ - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: epub_show_urls :type: :code-py:`'footnote' | 'no' | 'inline'` @@ -2795,7 +2795,7 @@ so the HTML options also apply where appropriate. The display of inline URLs can be customised by adding CSS rules for the class ``link-target``. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: epub_use_index :type: :code-py:`bool` @@ -2803,7 +2803,7 @@ so the HTML options also apply where appropriate. Add an index to the EPUB document. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: epub_writing_mode :type: :code-py:`'horizontal' | 'vertical'` @@ -2887,17 +2887,17 @@ These options influence LaTeX output. to keep a Unicode literal such as ``α`` (U+03B1) as-is in output, rather than being rendered as :math:`\alpha`. - .. versionchanged:: 2.1.0 + .. version-changed:: 2.1.0 Use ``'xelatex'`` (and LaTeX package ``xeCJK``) by default for Chinese documents. - .. versionchanged:: 2.2.1 + .. version-changed:: 2.2.1 Use ``'xelatex'`` by default for Greek documents. - .. versionchanged:: 2.3 + .. version-changed:: 2.3 Add ``'uplatex'`` support. - .. versionchanged:: 4.0 + .. version-changed:: 4.0 Use ``'uplatex'`` by default for Japanese documents. .. confval:: latex_documents @@ -2946,11 +2946,11 @@ These options influence LaTeX output. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output. - .. versionadded:: 0.3 + .. version-added:: 0.3 The 6th item ``toctree_only``. Tuples with 5 items are still accepted. - .. versionadded:: 1.2 + .. version-added:: 1.2 In the past including your own document class required you to prepend the document class name with the string "sphinx". This is not necessary anymore. @@ -2979,7 +2979,7 @@ These options influence LaTeX output. :code-tex:`\\chapter` numbering (or :code-tex:`\\section` for ``'howto'`` theme) when encountering :code-tex:`\\part` command. - .. versionadded:: 1.4 + .. version-added:: 1.4 .. confval:: latex_appendices :type: :code-py:`Sequence[str]` @@ -3007,8 +3007,8 @@ These options influence LaTeX output. 'py-modindex', } - .. versionadded:: 1.0 - .. versionchanged:: 7.4 + .. version-added:: 1.0 + .. version-changed:: 7.4 Permit and prefer a set type. .. confval:: latex_show_pagerefs @@ -3018,7 +3018,7 @@ These options influence LaTeX output. Add page references after internal references. This is very useful for printed copies of the manual. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: latex_show_urls :type: :code-py:`'no' | 'footnote' | 'inline'` @@ -3035,8 +3035,8 @@ These options influence LaTeX output. :code-py:`'inline'` Display URLs inline in parentheses - .. versionadded:: 1.0 - .. versionchanged:: 1.1 + .. version-added:: 1.0 + .. version-changed:: 1.1 This value is now a string; previously it was a boolean value, and a true value selected the :code-py:`'inline'` display. For backwards compatibility, :code-py:`True` is still accepted. @@ -3059,7 +3059,7 @@ These options influence LaTeX output. and also with multiple paragraphs in such cells if the table is rendered using ``tabulary``. - .. versionadded:: 1.6 + .. version-added:: 1.6 .. confval:: latex_table_style :type: :code-py:`list[str]` @@ -3166,9 +3166,9 @@ These options influence LaTeX output. .. _colortbl: https://ctan.org/pkg/colortbl .. _xcolor: https://ctan.org/pkg/xcolor - .. versionadded:: 5.3.0 + .. version-added:: 5.3.0 - .. versionchanged:: 6.0.0 + .. version-changed:: 6.0.0 Modify default from :code-py:`[]` to :code-py:`['booktabs', 'colorrows']`. @@ -3208,13 +3208,13 @@ These options influence LaTeX output. Cyrillic documents handle the indexing of Latin names correctly, even those having diacritics. - .. versionadded:: 1.8 + .. version-added:: 1.8 .. confval:: latex_elements :type: :code-py:`dict[str, str]` :default: :code-py:`{}` - .. versionadded:: 0.5 + .. version-added:: 0.5 :ref:`See the full documentation for latex_elements `. @@ -3228,9 +3228,9 @@ These options influence LaTeX output. Default is to use :code-py:`'article'` for :code-py:`'howto'` and :code-py:`'report'` for :code-py:`'manual'`. - .. versionadded:: 1.0 + .. version-added:: 1.0 - .. versionchanged:: 1.5 + .. version-changed:: 1.5 In Japanese documentation (:confval:`language` is :code-py:`'ja'`), by default :code-py:`'jreport'` is used for :code-py:`'howto'` and :code-py:`'jsbook'` for :code-py:`'manual'`. @@ -3256,9 +3256,9 @@ These options influence LaTeX output. you must add a further suffix such as ``.txt`` to the filename and adjust the :code-tex:`\\input{}` macro accordingly. - .. versionadded:: 0.6 + .. version-added:: 0.6 - .. versionchanged:: 1.2 + .. version-changed:: 1.2 This overrides the files provided from Sphinx such as ``sphinx.sty``. .. confval:: latex_theme @@ -3282,7 +3282,7 @@ These options influence LaTeX output. (Japanese documents use ``jreport``). :confval:`latex_appendices` is only available for this theme. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. confval:: latex_theme_options :type: :code-py:`dict[str, Any]` @@ -3292,7 +3292,7 @@ These options influence LaTeX output. look and feel of the selected theme. These are theme-specific. - .. versionadded:: 3.1 + .. version-added:: 3.1 .. confval:: latex_theme_path :type: :code-py:`list[str]` @@ -3301,7 +3301,7 @@ These options influence LaTeX output. A list of paths that contain custom LaTeX themes as subdirectories. Relative paths are taken as relative to the :term:`configuration directory`. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. _text-options: @@ -3317,7 +3317,7 @@ These options influence text output. Include section numbers in text output. - .. versionadded:: 1.7 + .. version-added:: 1.7 .. confval:: text_newlines :type: :code-py:`'unix' | 'windows' | 'native'` @@ -3332,7 +3332,7 @@ These options influence text output. :code-py:`'native'` Use the line ending style of the platform the documentation is built on. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: text_secnumber_suffix :type: :code-py:`str` @@ -3341,7 +3341,7 @@ These options influence text output. Suffix for section numbers in text output. Set to :code-py:`' '` to suppress the final dot on section numbers. - .. versionadded:: 1.7 + .. version-added:: 1.7 .. confval:: text_sectionchars :type: :code-py:`str` @@ -3351,7 +3351,7 @@ These options influence text output. The first character is used for first-level headings, the second for second-level headings and so on. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. _man-options: @@ -3400,7 +3400,7 @@ These options influence manual page output. The manual page section. Used for the output file name as well as in the manual page header. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. confval:: man_show_urls :type: :code-py:`bool` @@ -3408,7 +3408,7 @@ These options influence manual page output. Add URL addresses after links. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: man_make_section_directory :type: :code-py:`bool` @@ -3416,12 +3416,12 @@ These options influence manual page output. Make a section directory on build man page. - .. versionadded:: 3.3 + .. version-added:: 3.3 - .. versionchanged:: 4.0 + .. version-changed:: 4.0 The default is now :code-py:`False` (previously :code-py:`True`). - .. versionchanged:: 4.0.2 + .. version-changed:: 4.0.2 Revert the change in the default. @@ -3482,7 +3482,7 @@ These options influence Texinfo output. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo output. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: texinfo_appendices :type: :code-py:`Sequence[str]` @@ -3490,7 +3490,7 @@ These options influence Texinfo output. A list of document names to append as an appendix to all manuals. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: texinfo_cross_references :type: :code-py:`bool` @@ -3500,7 +3500,7 @@ These options influence Texinfo output. Disabling inline references can make an info file more readable with a stand-alone reader (``info``). - .. versionadded:: 4.4 + .. version-added:: 4.4 .. confval:: texinfo_domain_indices :type: :code-py:`bool | Sequence[str]` @@ -3521,8 +3521,8 @@ These options influence Texinfo output. 'py-modindex', } - .. versionadded:: 1.1 - .. versionchanged:: 7.4 + .. version-added:: 1.1 + .. version-changed:: 7.4 Permit and prefer a set type. .. confval:: texinfo_elements @@ -3557,7 +3557,7 @@ These options influence Texinfo output. ``'author'``, ``'body'``, ``'date'``, ``'direntry'`` ``'filename'``, ``'project'``, ``'release'``, and ``'title'``. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: texinfo_no_detailmenu :type: :code-py:`bool` @@ -3566,7 +3566,7 @@ These options influence Texinfo output. Do not generate a ``@detailmenu`` in the "Top" node's menu containing entries for each sub-node in the document. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: texinfo_show_urls :type: :code-py:`'footnote' | 'no' | 'inline'` @@ -3582,7 +3582,7 @@ These options influence Texinfo output. :code-py:`'inline'` Display URLs inline in parentheses. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. _qthelp-options: @@ -3632,7 +3632,7 @@ Options for XML output Pretty-print the XML. - .. versionadded:: 1.2 + .. version-added:: 1.2 Options for the linkcheck builder @@ -3669,9 +3669,9 @@ and which failures and redirects it ignores. r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*' } - .. versionadded:: 4.1 + .. version-added:: 4.1 - .. versionchanged:: 8.3 + .. version-changed:: 8.3 Setting :confval:`!linkcheck_allowed_redirects` to an empty dictionary may now be used to warn on all redirects encountered by the *linkcheck* builder. @@ -3684,7 +3684,7 @@ and which failures and redirects it ignores. Since this requires downloading the whole document, it is considerably slower when enabled. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. confval:: linkcheck_anchors_ignore :type: :code-py:`Sequence[str]` @@ -3711,7 +3711,7 @@ and which failures and redirects it ignores. 'https://www.sphinx-doc.org/en/1.7/intro.html#', ] - .. versionadded:: 1.5 + .. version-added:: 1.5 .. confval:: linkcheck_anchors_ignore_for_url :type: :code-py:`Sequence[str]` @@ -3722,7 +3722,7 @@ and which failures and redirects it ignores. This allows skipping anchor checks on a per-page basis while still checking the validity of the page itself. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. confval:: linkcheck_exclude_documents :type: :code-py:`Sequence[str]` @@ -3740,7 +3740,7 @@ and which failures and redirects it ignores. # ignore all links in documents located in a subdirectory named 'legacy' linkcheck_exclude_documents = [r'.*/legacy/.*'] - .. versionadded:: 4.4 + .. version-added:: 4.4 .. confval:: linkcheck_ignore :type: :code-py:`Sequence[str]` @@ -3758,7 +3758,7 @@ and which failures and redirects it ignores. linkcheck_ignore = [r'https://localhost:\d+/'] - .. versionadded:: 1.1 + .. version-added:: 1.1 HTTP Requests ~~~~~~~~~~~~~ @@ -3795,7 +3795,7 @@ and the number of workers to use. ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)), ] - .. versionadded:: 2.3 + .. version-added:: 2.3 .. confval:: linkcheck_allow_unauthorized :type: :code-py:`bool` @@ -3806,12 +3806,12 @@ and the number of workers to use. to treat the link as "broken". To change that behaviour, set this option to :code-py:`True`. - .. versionchanged:: 8.0 + .. version-changed:: 8.0 The default value for this option changed to :code-py:`False`, meaning HTTP 401 responses to checked hyperlinks are treated as "broken" by default. - .. versionadded:: 7.3 + .. version-added:: 7.3 .. confval:: linkcheck_rate_limit_timeout :type: :code-py:`int` @@ -3833,7 +3833,7 @@ and the number of workers to use. .. _Retry-After: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3 - .. versionadded:: 3.4 + .. version-added:: 3.4 .. confval:: linkcheck_report_timeouts_as_broken :type: :code-py:`bool` @@ -3844,12 +3844,12 @@ and the number of workers to use. by default. To report timeouts as ``broken`` instead, you can set :confval:`linkcheck_report_timeouts_as_broken` to :code-py:`True`. - .. versionchanged:: 8.0 + .. version-changed:: 8.0 The default value for this option changed to :code-py:`False`, meaning timeouts that occur while checking hyperlinks will be reported using the new 'timeout' status code. - .. versionadded:: 7.3 + .. version-added:: 7.3 .. confval:: linkcheck_request_headers :type: :code-py:`dict[str, dict[str, str]]` @@ -3877,7 +3877,7 @@ and the number of workers to use. } } - .. versionadded:: 3.1 + .. version-added:: 3.1 .. confval:: linkcheck_retries :type: :code-py:`int` @@ -3886,7 +3886,7 @@ and the number of workers to use. The number of times the *linkcheck* builder will attempt to check a URL before declaring it broken. - .. versionadded:: 1.4 + .. version-added:: 1.4 .. confval:: linkcheck_timeout :type: :code-py:`int` @@ -3895,7 +3895,7 @@ and the number of workers to use. The duration, in seconds, that the *linkcheck* builder will wait for a response after each hyperlink request. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: linkcheck_workers :type: :code-py:`int` @@ -3903,7 +3903,7 @@ and the number of workers to use. The number of worker threads to use when checking links. - .. versionadded:: 1.1 + .. version-added:: 1.1 Domain options @@ -3923,8 +3923,8 @@ Options for the C domain A list of identifiers to be recognised as keywords by the C parser. - .. versionadded:: 4.0.3 - .. versionchanged:: 7.4 + .. version-added:: 4.0.3 + .. version-changed:: 7.4 :confval:`!c_extra_keywords` can now be a set. .. confval:: c_id_attributes @@ -3944,8 +3944,8 @@ Options for the C domain 'my_id_attribute', ] - .. versionadded:: 3.0 - .. versionchanged:: 7.4 + .. version-added:: 3.0 + .. version-changed:: 7.4 :confval:`!c_id_attributes` can now be a tuple. .. confval:: c_maximum_signature_line_length @@ -3962,7 +3962,7 @@ Options for the C domain This is a domain-specific setting, overriding :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. confval:: c_paren_attributes :type: :code-py:`Sequence[str]` @@ -3985,8 +3985,8 @@ Options for the C domain 'my_align_as', ] - .. versionadded:: 3.0 - .. versionchanged:: 7.4 + .. version-added:: 3.0 + .. version-changed:: 7.4 :confval:`!c_paren_attributes` can now be a tuple. @@ -4012,8 +4012,8 @@ Options for the C++ domain 'my_id_attribute', ] - .. versionadded:: 1.5 - .. versionchanged:: 7.4 + .. version-added:: 1.5 + .. version-changed:: 7.4 :confval:`!cpp_id_attributes` can now be a tuple. .. confval:: cpp_index_common_prefix @@ -4031,7 +4031,7 @@ Options for the C++ domain 'awesome_lib::', ] - .. versionadded:: 1.5 + .. version-added:: 1.5 .. confval:: cpp_maximum_signature_line_length :type: :code-py:`int | None` @@ -4047,7 +4047,7 @@ Options for the C++ domain This is a domain-specific setting, overriding :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. confval:: cpp_paren_attributes :type: :code-py:`Sequence[str]` @@ -4070,8 +4070,8 @@ Options for the C++ domain 'my_align_as', ] - .. versionadded:: 1.5 - .. versionchanged:: 7.4 + .. version-added:: 1.5 + .. version-changed:: 7.4 :confval:`!cpp_paren_attributes` can now be a tuple. @@ -4092,7 +4092,7 @@ Options for the Javascript domain This is a domain-specific setting, overriding :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. confval:: javascript_trailing_comma_in_multi_line_signatures :type: :code-py:`bool` @@ -4100,7 +4100,7 @@ Options for the Javascript domain Use a trailing comma in parameter lists spanning multiple lines, if true. - .. versionadded:: 8.2 + .. version-added:: 8.2 Options for the Python domain @@ -4128,7 +4128,7 @@ Options for the Python domain .. caution:: Works only for the HTML builder currently. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. confval:: python_display_short_literal_types :type: :code-py:`bool` @@ -4159,7 +4159,7 @@ Options for the Python domain serve_food(item: "egg" | "spam" | "lobster thermidor") -> None - .. versionadded:: 6.2 + .. version-added:: 6.2 .. confval:: python_maximum_signature_line_length :type: :code-py:`int | None` @@ -4189,7 +4189,7 @@ Options for the Python domain .. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U) - .. versionadded:: 7.1 + .. version-added:: 7.1 .. confval:: python_trailing_comma_in_multi_line_signatures :type: :code-py:`bool` @@ -4197,7 +4197,7 @@ Options for the Python domain Use a trailing comma in parameter lists spanning multiple lines, if true. - .. versionadded:: 8.2 + .. version-added:: 8.2 .. confval:: python_use_unqualified_type_names :type: :code-py:`bool` @@ -4205,7 +4205,7 @@ Options for the Python domain Suppress the module name of the python reference if it can be resolved. - .. versionadded:: 4.0 + .. version-added:: 4.0 .. caution:: This feature is experimental. @@ -4220,8 +4220,8 @@ Options for the Python domain See the extension :mod:`~sphinx.ext.doctest` for more possibilities of including doctests. - .. versionadded:: 1.0 - .. versionchanged:: 1.1 + .. version-added:: 1.0 + .. version-changed:: 1.1 Now also removes ````. diff --git a/doc/usage/domains/c.rst b/doc/usage/domains/c.rst index 49aa5caee1c..d6b24ad8c48 100644 --- a/doc/usage/domains/c.rst +++ b/doc/usage/domains/c.rst @@ -4,7 +4,7 @@ The C Domain ============ -.. versionadded:: 1.0 +.. version-added:: 1.0 The C domain (name **c**) is suited for documentation of C API. @@ -39,7 +39,7 @@ The C domain (name **c**) is suited for documentation of C API. * ``retval``, ``retvals``: An alternative to ``returns`` for describing the result of the function. - .. versionadded:: 4.3 + .. version-added:: 4.3 The ``retval`` field type. For example:: @@ -74,7 +74,7 @@ The C domain (name **c**) is suited for documentation of C API. line, overriding :confval:`c_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. c:macro:: name @@ -86,7 +86,7 @@ The C domain (name **c**) is suited for documentation of C API. In the description of a macro you can use the same info fields as for the :rst:dir:`c:function` directive. - .. versionadded:: 3.0 + .. version-added:: 3.0 The function style variant. .. rst:directive:option:: single-line-parameter-list @@ -96,31 +96,31 @@ The C domain (name **c**) is suited for documentation of C API. line, overriding :confval:`c_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. c:struct:: name Describes a C struct. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. rst:directive:: .. c:union:: name Describes a C union. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. rst:directive:: .. c:enum:: name Describes a C enum. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. rst:directive:: .. c:enumerator:: name Describes a C enumerator. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. rst:directive:: .. c:type:: typedef-like declaration .. c:type:: name @@ -151,7 +151,7 @@ are defined in the documentation: Note that :rst:role:`c:member`, :rst:role:`c:data`, and :rst:role:`c:var` are equivalent. - .. versionadded:: 3.0 + .. version-added:: 3.0 The var, struct, union, enum, and enumerator roles. @@ -198,7 +198,7 @@ This will be rendered as: Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. -.. versionadded:: 3.0 +.. version-added:: 3.0 Aliasing Declarations @@ -236,7 +236,7 @@ The following directive can be used for this purpose. .. c:alias:: data f - .. versionadded:: 3.2 + .. version-added:: 3.2 .. rubric:: Options @@ -247,14 +247,14 @@ The following directive can be used for this purpose. Use 0 for infinite depth and 1 for just the mentioned declaration. Defaults to 1. - .. versionadded:: 3.3 + .. version-added:: 3.3 .. rst:directive:option:: noroot Skip the mentioned declarations and only render nested declarations. Requires ``maxdepth`` either 0 or at least 2. - .. versionadded:: 3.5 + .. version-added:: 3.5 .. c:namespace-pop:: @@ -293,13 +293,13 @@ Inline Expressions and Types A type: :c:expr:`const Data*` (or as text :c:texpr:`const Data*`). - .. versionadded:: 3.0 + .. version-added:: 3.0 Namespacing ----------- -.. versionadded:: 3.1 +.. version-added:: 3.1 The C language it self does not support namespacing, but it can sometimes be useful to emulate it in documentation, e.g., to show alternate declarations. diff --git a/doc/usage/domains/cpp.rst b/doc/usage/domains/cpp.rst index 57cb932e496..8bb1caddd05 100644 --- a/doc/usage/domains/cpp.rst +++ b/doc/usage/domains/cpp.rst @@ -4,7 +4,7 @@ The C++ Domain ============== -.. versionadded:: 1.0 +.. version-added:: 1.0 The C++ domain (name **cpp**) supports documenting C++ projects. @@ -46,7 +46,7 @@ visibility statement (``public``, ``private`` or ``protected``). .. cpp:class:: template \ std::array - .. versionadded:: 2.0 + .. version-added:: 2.0 The :rst:dir:`cpp:struct` directive. .. rst:directive:: .. cpp:function:: (member) function prototype @@ -94,7 +94,7 @@ visibility statement (``public``, ``private`` or ``protected``). line, overriding :confval:`cpp_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. cpp:member:: (member) variable declaration .. cpp:var:: (member) variable declaration @@ -199,7 +199,7 @@ visibility statement (``public``, ``private`` or ``protected``). Describe a union. - .. versionadded:: 1.8 + .. version-added:: 1.8 .. rst:directive:: .. cpp:concept:: template-parameter-list name @@ -248,7 +248,7 @@ visibility statement (``public``, ``private`` or ``protected``). - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` is incrementable. - .. versionadded:: 1.5 + .. version-added:: 1.5 Options @@ -260,7 +260,7 @@ Some directives support options: - ``:tparam-line-spec:``, for templated declarations. If specified, each template parameter will be rendered on a separate line. - .. versionadded:: 1.6 + .. version-added:: 1.6 Anonymous Entities ------------------ @@ -305,7 +305,7 @@ This will be rendered as: Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. -.. versionadded:: 1.8 +.. version-added:: 1.8 Aliasing Declarations @@ -342,7 +342,7 @@ The following directive can be used for this purpose. .. cpp:alias:: void overload_example::C::f(double d) const void overload_example::C::f(double d) - .. versionadded:: 2.0 + .. version-added:: 2.0 .. rubric:: Options @@ -353,14 +353,14 @@ The following directive can be used for this purpose. Use 0 for infinite depth and 1 for just the mentioned declaration. Defaults to 1. - .. versionadded:: 3.5 + .. version-added:: 3.5 .. rst:directive:option:: noroot Skip the mentioned declarations and only render nested declarations. Requires ``maxdepth`` either 0 or at least 2. - .. versionadded:: 3.5 + .. version-added:: 3.5 Constrained Templates @@ -456,10 +456,10 @@ Inline Expressions and Types A type: :cpp:expr:`const MySortedContainer&` (or as text :cpp:texpr:`const MySortedContainer&`). - .. versionadded:: 1.7 + .. version-added:: 1.7 The :rst:role:`cpp:expr` role. - .. versionadded:: 1.8 + .. version-added:: 1.8 The :rst:role:`cpp:texpr` role. Namespacing @@ -523,7 +523,7 @@ The ``cpp:namespace-pop`` directive undoes the most recent the current scope will be ``A::B::C::D``. - .. versionadded:: 1.4 + .. version-added:: 1.4 .. rst:directive:: .. cpp:namespace-pop:: @@ -546,7 +546,7 @@ The ``cpp:namespace-pop`` directive undoes the most recent .. cpp:namespace-push:: A::B - .. versionadded:: 1.4 + .. version-added:: 1.4 Info field lists ---------------- @@ -565,7 +565,7 @@ following fields: the result of the function. * ``throws``, ``throw``, ``exception``: Description of a possibly thrown exception. -.. versionadded:: 4.3 +.. version-added:: 4.3 The ``retval`` field type. .. _cpp-xref-roles: @@ -589,7 +589,7 @@ These roles link to the given declaration types: Reference a C++ declaration by name (see below for details). The name must be properly qualified relative to the position of the link. - .. versionadded:: 2.0 + .. version-added:: 2.0 The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class` role. diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst index fac8e94e8e8..bf0d85f559f 100644 --- a/doc/usage/domains/index.rst +++ b/doc/usage/domains/index.rst @@ -6,7 +6,7 @@ Domains ======= -.. versionadded:: 1.0 +.. version-added:: 1.0 Originally, Sphinx was conceived for a single project, the documentation of the Python language. Shortly afterwards, it was made available for everyone as a @@ -125,19 +125,19 @@ index entry for later reference. Though, note that not every directive in every domain may support these options. -.. versionadded:: 3.2 +.. version-added:: 3.2 The directive option ``noindexentry`` in the Python, C, C++, and Javascript domains. -.. versionadded:: 5.2.3 +.. version-added:: 5.2.3 The directive option ``:nocontentsentry:`` in the Python, C, C++, Javascript, and reStructuredText domains. -.. versionadded:: 7.2 +.. version-added:: 7.2 The directive option ``no-typesetting`` in the Python, C, C++, Javascript, and reStructuredText domains. -.. versionchanged:: 7.2 +.. version-changed:: 7.2 * The directive option ``:noindex:`` was renamed to ``:no-index:``. diff --git a/doc/usage/domains/javascript.rst b/doc/usage/domains/javascript.rst index ba0ff101a52..b26c1feaba5 100644 --- a/doc/usage/domains/javascript.rst +++ b/doc/usage/domains/javascript.rst @@ -4,7 +4,7 @@ The JavaScript Domain ===================== -.. versionadded:: 1.0 +.. version-added:: 1.0 The JavaScript domain (name **js**) provides the following directives: @@ -20,8 +20,8 @@ The JavaScript domain (name **js**) provides the following directives: specified. If this option is specified, the directive will only update the current module name. - .. versionadded:: 1.6 - .. versionchanged:: 5.2 + .. version-added:: 1.6 + .. version-changed:: 5.2 Module directives support body content. @@ -66,14 +66,14 @@ The JavaScript domain (name **js**) provides the following directives: line, overriding :confval:`javascript_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. js:method:: name(signature) This directive is an alias for :rst:dir:`js:function`, however it describes a function that is implemented as a method on a class object. - .. versionadded:: 1.6 + .. version-added:: 1.6 .. rst:directive:option:: single-line-parameter-list :type: no value @@ -82,7 +82,7 @@ The JavaScript domain (name **js**) provides the following directives: line, overriding :confval:`javascript_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. js:class:: name @@ -110,7 +110,7 @@ The JavaScript domain (name **js**) provides the following directives: line, overriding :confval:`javascript_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. js:data:: name diff --git a/doc/usage/domains/mathematics.rst b/doc/usage/domains/mathematics.rst index 9f02c6dc978..12afdbd8f21 100644 --- a/doc/usage/domains/mathematics.rst +++ b/doc/usage/domains/mathematics.rst @@ -4,7 +4,7 @@ The Mathematics Domain ====================== -.. versionadded:: 1.8 +.. version-added:: 1.8 The math domain (name **math**) provides the following roles: @@ -19,4 +19,4 @@ The math domain (name **math**) provides the following roles: Euler's identity, equation :math:numref:`euler`, was elected one of the most beautiful mathematical formulas. - .. versionadded:: 1.8 + .. version-added:: 1.8 diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst index 8d47a6e0221..0117339269b 100644 --- a/doc/usage/domains/python.rst +++ b/doc/usage/domains/python.rst @@ -4,7 +4,7 @@ The Python Domain ================= -.. versionadded:: 1.0 +.. version-added:: 1.0 The Python domain (name **py**) provides the following directives for module declarations: @@ -18,7 +18,7 @@ declarations: This directive will also cause an entry in the global module index. - .. versionchanged:: 5.2 + .. version-changed:: 5.2 Module directives support body content. @@ -86,7 +86,7 @@ The following directives are provided for module and class contents: Indicate the function is an async function. - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rst:directive:option:: canonical :type: full qualified name including module name @@ -94,7 +94,7 @@ The following directives are provided for module and class contents: Describe the location where the object is defined if the object is imported from other modules - .. versionadded:: 4.0 + .. version-added:: 4.0 .. rst::directive:option:: module :type: text @@ -109,7 +109,7 @@ The following directives are provided for module and class contents: line, overriding :confval:`python_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:option:: single-line-type-parameter-list :type: no value @@ -118,7 +118,7 @@ The following directives are provided for module and class contents: logical line, overriding :confval:`python_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. py:data:: name @@ -145,12 +145,12 @@ The following directives are provided for module and class contents: meaning unions must use ``|`` and sequences must use square brackets, and roles such as ``:ref:`...``` cannot be used. - .. versionadded:: 2.4 + .. version-added:: 2.4 .. rst:directive:option:: value: initial value of the variable :type: text - .. versionadded:: 2.4 + .. version-added:: 2.4 .. rst:directive:option:: canonical :type: full qualified name including module name @@ -158,7 +158,7 @@ The following directives are provided for module and class contents: Describe the location where the object is defined if the object is imported from other modules - .. versionadded:: 4.0 + .. version-added:: 4.0 .. rst::directive:option:: module :type: text @@ -181,7 +181,7 @@ The following directives are provided for module and class contents: Indicate the class is a final class. - .. versionadded:: 3.1 + .. version-added:: 3.1 .. rst::directive:option:: module :type: text @@ -194,14 +194,14 @@ The following directives are provided for module and class contents: See :rst:dir:`py:class:single-line-parameter-list`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:option:: single-line-type-parameter-list :type: no value See :rst:dir:`py:class:single-line-type-parameter-list`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:: .. py:class:: name .. py:class:: name(parameters) @@ -242,7 +242,7 @@ The following directives are provided for module and class contents: A cheesy representation. - .. versionadded:: 8.2 + .. version-added:: 8.2 .. rst:directive:option:: canonical :type: full qualified name including module name @@ -250,14 +250,14 @@ The following directives are provided for module and class contents: Describe the location where the object is defined if the object is imported from other modules - .. versionadded:: 4.0 + .. version-added:: 4.0 .. rst:directive:option:: final :type: no value Indicate the class is a final class. - .. versionadded:: 3.1 + .. version-added:: 3.1 .. rst::directive:option:: module :type: text @@ -272,7 +272,7 @@ The following directives are provided for module and class contents: logical line, overriding :confval:`python_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:option:: single-line-type-parameter-list :type: no value @@ -305,12 +305,12 @@ The following directives are provided for module and class contents: meaning unions must use ``|`` and sequences must use square brackets, and roles such as ``:ref:`...``` cannot be used. - .. versionadded:: 2.4 + .. version-added:: 2.4 .. rst:directive:option:: value: initial value of the attribute :type: text - .. versionadded:: 2.4 + .. version-added:: 2.4 .. rst:directive:option:: canonical :type: full qualified name including module name @@ -318,7 +318,7 @@ The following directives are provided for module and class contents: Describe the location where the object is defined if the object is imported from other modules - .. versionadded:: 4.0 + .. version-added:: 4.0 .. rst::directive:option:: module :type: text @@ -330,7 +330,7 @@ The following directives are provided for module and class contents: Describes an object property. - .. versionadded:: 4.0 + .. version-added:: 4.0 .. rubric:: options @@ -347,7 +347,7 @@ The following directives are provided for module and class contents: Cheese levels at the *National Cheese Emporium*. - .. versionchanged:: 8.2 + .. version-changed:: 8.2 The ``:abstract:`` alias is also supported. @@ -356,7 +356,7 @@ The following directives are provided for module and class contents: Indicate the property is a classmethod. - .. versionadded:: 4.2 + .. version-added:: 4.2 .. rst:directive:option:: type: type of the property :type: text @@ -426,7 +426,7 @@ The following directives are provided for module and class contents: Represent a regular expression or a compiled pattern. - .. versionadded:: 7.4 + .. version-added:: 7.4 .. rst:directive:: .. py:method:: name(parameters) .. py:method:: name[type parameters](parameters) @@ -451,8 +451,8 @@ The following directives are provided for module and class contents: Order more cheese (we're fresh out!). - .. versionadded:: 2.1 - .. versionchanged:: 8.2 + .. version-added:: 2.1 + .. version-changed:: 8.2 The ``:abstract:`` alias is also supported. @@ -461,7 +461,7 @@ The following directives are provided for module and class contents: Indicate the method is an async method. - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rst:directive:option:: canonical :type: full qualified name including module name @@ -469,21 +469,21 @@ The following directives are provided for module and class contents: Describe the location where the object is defined if the object is imported from other modules - .. versionadded:: 4.0 + .. version-added:: 4.0 .. rst:directive:option:: classmethod :type: no value Indicate the method is a class method. - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rst:directive:option:: final :type: no value Indicate the method is a final method. - .. versionadded:: 3.1 + .. version-added:: 3.1 .. rst::directive:option:: module :type: text @@ -498,7 +498,7 @@ The following directives are provided for module and class contents: line, overriding :confval:`python_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:option:: single-line-type-parameter-list :type: no value @@ -507,14 +507,14 @@ The following directives are provided for module and class contents: line, overriding :confval:`python_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.2 + .. version-added:: 7.2 .. rst:directive:option:: staticmethod :type: no value Indicate the method is a static method. - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rst:directive:: .. py:staticmethod:: name(parameters) @@ -522,14 +522,14 @@ The following directives are provided for module and class contents: Like :rst:dir:`py:method`, but indicates that the method is a static method. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. rst:directive:: .. py:classmethod:: name(parameters) .. py:classmethod:: name[type parameters](parameters) Like :rst:dir:`py:method`, but indicates that the method is a class method. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:directive:: .. py:decorator:: name .. py:decorator:: name(parameters) @@ -571,7 +571,7 @@ The following directives are provided for module and class contents: line, overriding :confval:`python_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.1 + .. version-added:: 7.1 .. rst:directive:option:: single-line-type-parameter-list :type: no value @@ -580,7 +580,7 @@ The following directives are provided for module and class contents: logical line, overriding :confval:`python_maximum_signature_line_length` and :confval:`maximum_signature_line_length`. - .. versionadded:: 7.2 + .. version-added:: 7.2 .. rst:directive:: .. py:decoratormethod:: name .. py:decoratormethod:: name(signature) @@ -656,8 +656,8 @@ The corresponding reStructuredText markup would be: Info field lists ---------------- -.. versionadded:: 0.4 -.. versionchanged:: 3.0 +.. version-added:: 0.4 +.. version-changed:: 3.0 meta fields are added. @@ -725,7 +725,7 @@ single word, like this:: :param int priority: The priority of the message, can be a number 1-5 -.. versionadded:: 1.5 +.. version-added:: 1.5 Container types such as lists and dictionaries can be linked automatically using the following syntax:: @@ -817,7 +817,7 @@ a matching identifier is found: Reference an object of unspecified type. Useful e.g. as the :confval:`default_role`. - .. versionadded:: 0.4 + .. version-added:: 0.4 Target specification diff --git a/doc/usage/domains/restructuredtext.rst b/doc/usage/domains/restructuredtext.rst index a675ed55720..64ceb7f0909 100644 --- a/doc/usage/domains/restructuredtext.rst +++ b/doc/usage/domains/restructuredtext.rst @@ -4,7 +4,7 @@ The reStructuredText Domain =========================== -.. versionadded:: 1.0 +.. version-added:: 1.0 The reStructuredText domain (name **rst**) provides the following directives: @@ -74,7 +74,7 @@ The reStructuredText domain (name **rst**) provides the following directives: .. rst:directive:option:: maxdepth :type: integer or no value - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rst:directive:: .. rst:role:: name diff --git a/doc/usage/domains/standard.rst b/doc/usage/domains/standard.rst index dfc837fc2e1..73cc2bb104e 100644 --- a/doc/usage/domains/standard.rst +++ b/doc/usage/domains/standard.rst @@ -4,7 +4,7 @@ The Standard Domain =================== -.. versionadded:: 1.0 +.. version-added:: 1.0 The so-called "standard" domain collects all markup that doesn't warrant a domain of its own. Its directives and roles are not prefixed with a domain @@ -32,7 +32,7 @@ There is a set of directives allowing documenting command-line programs: referenceable by :rst:role:`option` (in the example case, you'd use something like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```). - .. versionchanged:: 5.3 + .. version-changed:: 5.3 One can cross-reference including an option value: ``:option:`--module=foobar```, ,``:option:`--module[=foobar]``` or ``:option:`--module foobar```. @@ -44,7 +44,7 @@ There is a set of directives allowing documenting command-line programs: .. rst:directive:: .. confval:: name - .. versionadded:: 7.4 + .. version-added:: 7.4 Describes a configuration value or setting that the documented code or program uses or defines. @@ -118,7 +118,7 @@ There is a set of directives allowing documenting command-line programs: The program name may contain spaces (in case you want to document subcommands like ``svn add`` and ``svn commit`` separately). - .. versionadded:: 0.5 + .. version-added:: 0.5 There is also a very generic object description directive, which is not tied to any domain: diff --git a/doc/usage/extensions/apidoc.rst b/doc/usage/extensions/apidoc.rst index 4dc8ca941a2..776dfdd79e4 100644 --- a/doc/usage/extensions/apidoc.rst +++ b/doc/usage/extensions/apidoc.rst @@ -10,7 +10,7 @@ .. index:: pair: generation; documentation .. index:: pair: generate; documentation -.. versionadded:: 8.2 +.. version-added:: 8.2 .. role:: code-py(code) :language: Python diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 1b873f0d819..f64f8555bd8 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -143,7 +143,7 @@ Marking objects as public or private :meta private: """ - .. versionadded:: 3.0 + .. version-added:: 3.0 * autodoc considers a member public if its docstring contains ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with @@ -158,7 +158,7 @@ Marking objects as public or private :meta public: """ - .. versionadded:: 3.1 + .. version-added:: 3.1 * autodoc considers a variable member does not have any default value if its docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`. @@ -168,7 +168,7 @@ Marking objects as public or private var1 = None #: :meta hide-value: - .. versionadded:: 3.5 + .. version-added:: 3.5 .. _doc-comment: @@ -324,7 +324,7 @@ Automatically document modules Do not generate an index entry for the documented module or any auto-documented members. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. rst:directive:option:: no-index-entry :type: @@ -333,7 +333,7 @@ Automatically document modules or any auto-documented members. Unlike ``:no-index:``, cross-references are still created. - .. versionadded:: 8.2 + .. version-added:: 8.2 .. rst:directive:option:: platform: platforms :type: comma separated list @@ -347,7 +347,7 @@ Automatically document modules A sentence describing the module's purpose. This is identical to :rst:dir:`py:module`'s ``:synopsis:`` option. - .. versionadded:: 0.5 + .. version-added:: 0.5 .. rst:directive:option:: deprecated :type: @@ -355,14 +355,14 @@ Automatically document modules Mark a module as deprecated. This is identical to :rst:dir:`py:module`'s ``:deprecated:`` option. - .. versionadded:: 0.5 + .. version-added:: 0.5 .. rst:directive:option:: ignore-module-all :type: no value Do not use ``__all__`` when analysing the module to document. - .. versionadded:: 1.7 + .. version-added:: 1.7 .. rubric:: Options for selecting members to document @@ -402,7 +402,7 @@ Automatically document modules :members: :exclude-members: NoodleBase - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:directive:option:: imported-members :type: no value @@ -419,7 +419,7 @@ Automatically document modules because attribute documentation is discovered by parsing the source file of the current module. - .. versionadded:: 1.2 + .. version-added:: 1.2 .. rst:directive:option:: undoc-members :type: @@ -456,8 +456,8 @@ Automatically document modules :members: :private-members: _spicy, _garlickly - .. versionadded:: 1.1 - .. versionchanged:: 3.2 + .. version-added:: 1.1 + .. version-changed:: 3.2 The option can now take a comma-separated list of arguments. .. rst:directive:option:: special-members @@ -483,9 +483,9 @@ Automatically document modules :members: :special-members: __version__ - .. versionadded:: 1.1 + .. version-added:: 1.1 - .. versionchanged:: 1.2 + .. version-changed:: 1.2 The option can now take a comma-separated list of arguments. .. rubric:: Options for documented members @@ -509,8 +509,8 @@ Automatically document modules Note that for source order, the module must be a Python module with the source code available. - .. versionadded:: 0.6 - .. versionchanged:: 1.0 + .. version-added:: 0.6 + .. version-changed:: 1.0 Support the ``'bysource'`` option. .. rst:directive:option:: show-inheritance @@ -520,7 +520,7 @@ Automatically document modules option for all members of the module, if ``:members:`` is enabled. - .. versionadded:: 0.4 + .. version-added:: 0.4 Automatically document classes or exceptions @@ -575,7 +575,7 @@ Automatically document classes or exceptions This is useful if the signature from the method is hidden by a decorator. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. rubric:: Options @@ -585,7 +585,7 @@ Automatically document classes or exceptions Do not generate an index entry for the documented class or any auto-documented members. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. rst:directive:option:: no-index-entry :type: @@ -594,7 +594,7 @@ Automatically document classes or exceptions or any auto-documented members. Unlike ``:no-index:``, cross-references are still created. - .. versionadded:: 8.2 + .. version-added:: 8.2 .. rst:directive:option:: class-doc-from :type: class, init, or both @@ -617,7 +617,7 @@ Automatically document classes or exceptions ``autodoc`` will attempt to use the :meth:`!__new__` method's docstring, if it exists and is not blank. - .. versionadded:: 4.1 + .. version-added:: 4.1 .. rubric:: Options for selecting members to document @@ -655,7 +655,7 @@ Automatically document classes or exceptions :members: :exclude-members: prepare - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:directive:option:: inherited-members :type: comma separated list @@ -688,13 +688,13 @@ Automatically document classes or exceptions reStructuredText for their docstrings, there may be markup warnings or errors. - .. versionadded:: 0.3 + .. version-added:: 0.3 - .. versionchanged:: 3.0 + .. version-changed:: 3.0 ``:inherited-members:`` now takes the name of a base class to exclude as an argument. - .. versionchanged:: 5.0 + .. version-changed:: 5.0 A comma separated list of base class names can be used. .. rst:directive:option:: undoc-members @@ -732,8 +732,8 @@ Automatically document classes or exceptions :members: :private-members: _spicy, _garlickly - .. versionadded:: 1.1 - .. versionchanged:: 3.2 + .. version-added:: 1.1 + .. version-changed:: 3.2 The option can now take arguments. .. rst:directive:option:: special-members @@ -759,9 +759,9 @@ Automatically document classes or exceptions :members: :special-members: __init__, __name__ - .. versionadded:: 1.1 + .. version-added:: 1.1 - .. versionchanged:: 1.2 + .. version-changed:: 1.2 The option can now take a comma-separated list of arguments. .. rubric:: Options for documented members @@ -785,8 +785,8 @@ Automatically document classes or exceptions Note that for source order, the module must be a Python module with the source code available. - .. versionadded:: 0.6 - .. versionchanged:: 1.0 + .. version-added:: 0.6 + .. version-changed:: 1.0 Support the ``'bysource'`` option. .. rst:directive:option:: show-inheritance @@ -794,7 +794,7 @@ Automatically document classes or exceptions Insert the class's base classes after the class signature. - .. versionadded:: 0.4 + .. version-added:: 0.4 Automatically document function-like objects @@ -833,9 +833,9 @@ Automatically document function-like objects .. note:: For more flexibility, use the :py:class:`!Noodle` class. - .. versionadded:: 2.0 + .. version-added:: 2.0 :rst:dir:`autodecorator`. - .. versionadded:: 2.1 + .. version-added:: 2.1 :rst:dir:`autoproperty`. .. note:: @@ -861,7 +861,7 @@ Automatically document function-like objects This is useful if the signature from the method is hidden by a decorator. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. rubric:: Options @@ -870,7 +870,7 @@ Automatically document function-like objects Do not generate an index entry for the documented function. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. rst:directive:option:: no-index-entry :type: @@ -878,7 +878,7 @@ Automatically document function-like objects Do not generate an index entry for the documented function. Unlike ``:no-index:``, cross-references are still created. - .. versionadded:: 8.2 + .. version-added:: 8.2 Automatically document attributes or data @@ -915,10 +915,10 @@ Automatically document attributes or data .. hint:: Cooking time can vary by which flour type is used. - .. versionchanged:: 0.6 + .. version-changed:: 0.6 :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings. - .. versionchanged:: 1.1 + .. version-changed:: 1.1 Doc-comments are now allowed on the same line of an assignment. .. rubric:: Options @@ -928,7 +928,7 @@ Automatically document attributes or data Do not generate an index entry for the documented variable or constant. - .. versionadded:: 0.4 + .. version-added:: 0.4 .. rst:directive:option:: no-index-entry :type: @@ -936,12 +936,12 @@ Automatically document attributes or data Do not generate an index entry for the documented variable or constant. Unlike ``:no-index:``, cross-references are still created. - .. versionadded:: 8.2 + .. version-added:: 8.2 .. rst:directive:option:: annotation: value :type: string - .. versionadded:: 1.2 + .. version-added:: 1.2 By default, ``autodoc`` attempts to obtain the type annotation and value of the variable by introspection, @@ -958,7 +958,7 @@ Automatically document attributes or data .. rst:directive:option:: no-value - .. versionadded:: 3.4 + .. version-added:: 3.4 To display the type hint of the variable without a value, use the ``:no-value:`` option. @@ -988,13 +988,13 @@ There are also config values that you can set: ``'init'`` Only the ``__init__`` method's docstring is inserted. - .. versionadded:: 0.3 + .. version-added:: 0.3 If the class has no ``__init__`` method or if the ``__init__`` method's docstring is empty, but the class has a ``__new__`` method's docstring, it is used instead. - .. versionadded:: 1.4 + .. version-added:: 1.4 .. confval:: autodoc_class_signature :type: :code-py:`str` @@ -1008,7 +1008,7 @@ There are also config values that you can set: ``'separated'`` Display the signature as a method. - .. versionadded:: 4.1 + .. version-added:: 4.1 .. confval:: autodoc_member_order :type: :code-py:`str` @@ -1033,8 +1033,8 @@ There are also config values that you can set: This requires that the module must be a Python module with the source code available. - .. versionadded:: 0.6 - .. versionchanged:: 1.0 + .. version-added:: 0.6 + .. version-changed:: 1.0 Support for ``'bysource'``. .. confval:: autodoc_default_options @@ -1075,18 +1075,18 @@ There are also config values that you can set: * ``'no-index'``: See :rst:dir:`automodule:no-index`. * ``'no-index-entry'``: See :rst:dir:`automodule:no-index-entry`. - .. versionadded:: 1.8 + .. version-added:: 1.8 - .. versionchanged:: 2.0 + .. version-changed:: 2.0 Accepts ``True`` as a value. - .. versionchanged:: 2.1 + .. version-changed:: 2.1 Added ``'imported-members'``. - .. versionchanged:: 4.1 + .. version-changed:: 4.1 Added ``'class-doc-from'``. - .. versionchanged:: 4.5 + .. version-changed:: 4.5 Added ``'no-value'``. .. confval:: autodoc_docstring_signature @@ -1107,12 +1107,12 @@ There are also config values that you can set: stopping at the first line that does not look like a signature. This is useful for declaring overloaded function signatures. - .. versionadded:: 1.1 - .. versionchanged:: 3.1 + .. version-added:: 1.1 + .. version-changed:: 3.1 Support overloaded signatures - .. versionchanged:: 4.0 + .. version-changed:: 4.0 Overloaded signatures do not need to be separated by a backslash @@ -1131,9 +1131,9 @@ There are also config values that you can set: Will mock all imports under the ``django`` package. - .. versionadded:: 1.3 + .. version-added:: 1.3 - .. versionchanged:: 1.6 + .. version-changed:: 1.6 This config value only requires to declare the top-level modules that should be mocked. @@ -1156,12 +1156,12 @@ There are also config values that you can set: description because it is impossible to accurately represent all possible overloads as a list of parameters. - .. versionadded:: 2.1 - .. versionadded:: 3.0 + .. version-added:: 2.1 + .. version-added:: 3.0 New option ``'description'`` is added. - .. versionadded:: 4.1 + .. version-added:: 4.1 New option ``'both'`` is added. @@ -1185,9 +1185,9 @@ There are also config values that you can set: parameter is documented in the docstring. The return type is always annotated (except if it is ``None``). - .. versionadded:: 4.0 + .. version-added:: 4.0 - .. versionadded:: 5.0 + .. version-added:: 5.0 New option ``'documented_params'`` is added. @@ -1234,7 +1234,7 @@ There are also config values that you can set: ... .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases - .. versionadded:: 3.3 + .. version-added:: 3.3 .. confval:: autodoc_typehints_format :type: :code-py:`str` @@ -1247,9 +1247,9 @@ There are also config values that you can set: * ``'short'`` -- Suppress the leading module names of the typehints (e.g. ``io.StringIO`` -> ``StringIO``) - .. versionadded:: 4.4 + .. version-added:: 4.4 - .. versionchanged:: 5.0 + .. version-changed:: 5.0 The default setting was changed to ``'short'`` @@ -1260,7 +1260,7 @@ There are also config values that you can set: If True, the default argument values of functions will be not evaluated on generating document. It preserves them as is in the source code. - .. versionadded:: 4.0 + .. version-added:: 4.0 Added as an experimental feature. This will be integrated into autodoc core in the future. @@ -1276,7 +1276,7 @@ There are also config values that you can set: for example if it exclusively uses type annotations or does not use type hints of any kind. - .. versionadded:: 8.2 + .. version-added:: 8.2 Added the option to disable the use of type comments in via the new :confval:`!autodoc_use_type_comments` option, @@ -1294,7 +1294,7 @@ There are also config values that you can set: If ``False`` is given, autodoc forcedly suppresses the error if the imported module emits warnings. - .. versionchanged:: 8.1 + .. version-changed:: 8.1 This option now has no effect as :option:`!--fail-on-warning` no longer exits early. @@ -1306,7 +1306,7 @@ There are also config values that you can set: If set to True the docstring for classes or methods, if not explicitly set, is inherited from parents. - .. versionadded:: 1.7 + .. version-added:: 1.7 .. confval:: suppress_warnings :no-index: @@ -1328,7 +1328,7 @@ autodoc provides the following additional events: .. event:: autodoc-process-docstring (app, what, name, obj, options, lines) - .. versionadded:: 0.4 + .. version-added:: 0.4 Emitted when autodoc has read and processed a docstring. *lines* is a list of strings -- the lines of the processed docstring -- that the event handler @@ -1348,7 +1348,7 @@ autodoc provides the following additional events: .. event:: autodoc-before-process-signature (app, obj, bound_method) - .. versionadded:: 2.4 + .. version-added:: 2.4 Emitted before autodoc formats a signature for an object. The event handler can modify an object to change its signature. @@ -1359,7 +1359,7 @@ autodoc provides the following additional events: .. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation) - .. versionadded:: 0.5 + .. version-added:: 0.5 Emitted when autodoc has formatted a signature for an object. The event handler can return a new tuple ``(signature, return_annotation)`` to change @@ -1400,8 +1400,8 @@ needed docstring processing in event :event:`autodoc-process-docstring`: :param options: the options given to the class directive :param bases: the list of base classes signature. see above. - .. versionadded:: 4.1 - .. versionchanged:: 4.3 + .. version-added:: 4.1 + .. version-changed:: 4.3 ``bases`` can contain a string as a base class name. It will be processed as reStructuredText. @@ -1415,7 +1415,7 @@ member should be included in the documentation by using the following event: .. event:: autodoc-skip-member (app, what, name, obj, skip, options) - .. versionadded:: 0.5 + .. version-added:: 0.5 Emitted when autodoc has to decide whether a member should be included in the documentation. The member is excluded if a handler returns ``True``. It is diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst index 1e9e1dba722..af4e2378518 100644 --- a/doc/usage/extensions/autosectionlabel.rst +++ b/doc/usage/extensions/autosectionlabel.rst @@ -6,7 +6,7 @@ .. module:: sphinx.ext.autosectionlabel :synopsis: Allow referencing sections by their title. -.. versionadded:: 1.4 +.. version-added:: 1.4 By default, cross-references to sections use labels (see :rst:role:`ref`). This extension allows you to instead refer to sections by their title. diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index c84dcb60eff..2675b85c797 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -6,7 +6,7 @@ .. module:: sphinx.ext.autosummary :synopsis: Generate autodoc summaries -.. versionadded:: 0.6 +.. version-added:: 0.6 .. role:: code-py(code) :language: Python @@ -74,7 +74,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes - .. versionadded:: 8.2 + .. version-added:: 8.2 .. rst:directive:option:: toctree: optional directory name @@ -94,13 +94,13 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: directory. If no argument is given, output is placed in the same directory as the file that contains the directive. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:directive:option:: caption: caption of ToC Add a caption to the toctree. - .. versionadded:: 3.1 + .. version-added:: 3.1 .. rst:directive:option:: signatures: format @@ -112,7 +112,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: arguments and as ``()`` if they don't have arguments. - ``none``: do not show signatures. - .. versionadded:: 8.2 + .. version-added:: 8.2 .. rst:directive:option:: nosignatures @@ -120,9 +120,9 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: This is equivalent to ``:signatures: none``. - .. versionadded:: 0.6 + .. version-added:: 0.6 - .. versionchanged:: 8.2 + .. version-changed:: 8.2 The directive option is superseded by the more general ``:signatures: none``. @@ -143,7 +143,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: :confval:`templates_path` to generate the pages for all entries listed. See `Customizing templates`_ below. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: recursive @@ -155,7 +155,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: sphinx.environment.BuildEnvironment - .. versionadded:: 3.1 + .. version-added:: 3.1 :program:`sphinx-autogen` -- generate autodoc stub pages @@ -198,7 +198,7 @@ also use these config values: A dictionary of values to pass into the template engine's context for autosummary stubs files. - .. versionadded:: 3.1 + .. version-added:: 3.1 .. confval:: autosummary_generate :type: :code-py:`bool` @@ -212,12 +212,12 @@ also use these config values: The new files will be placed in the directories specified in the ``:toctree:`` options of the directives. - .. versionchanged:: 2.3 + .. version-changed:: 2.3 Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc` does. - .. versionchanged:: 4.0 + .. version-changed:: 4.0 Enabled by default. @@ -227,7 +227,7 @@ also use these config values: If true, autosummary overwrites existing files by generated stub pages. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. confval:: autosummary_mock_imports :type: :code-py:`list[str]` @@ -237,7 +237,7 @@ also use these config values: See :confval:`autodoc_mock_imports` for more details. It defaults to :confval:`autodoc_mock_imports`. - .. versionadded:: 2.0 + .. version-added:: 2.0 .. confval:: autosummary_imported_members :type: :code-py:`bool` @@ -246,9 +246,9 @@ also use these config values: A boolean flag indicating whether to document classes and functions imported in modules. - .. versionadded:: 2.1 + .. version-added:: 2.1 - .. versionchanged:: 4.4 + .. version-changed:: 4.4 If ``autosummary_ignore_module_all`` is ``False``, this configuration value is ignored for members listed in ``__all__``. @@ -266,7 +266,7 @@ also use these config values: ``autosummary_ignore_module_all`` to False and ``autosummary_imported_members`` to True. - .. versionadded:: 4.4 + .. version-added:: 4.4 .. confval:: autosummary_filename_map :type: :code-py:`dict[str, str]` @@ -277,14 +277,14 @@ also use these config values: indistinguishable when case is ignored, on file systems where filenames are case-insensitive. - .. versionadded:: 3.2 + .. version-added:: 3.2 .. _autosummary-customizing-templates: Customizing templates --------------------- -.. versionadded:: 1.0 +.. version-added:: 1.0 You can customize the stub page templates, in a similar way as the HTML Jinja templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge` @@ -351,7 +351,7 @@ The following variables are available in the templates: List containing names of all inherited members of class. Only available for classes. - .. versionadded:: 1.8.0 + .. version-added:: 1.8.0 .. data:: functions @@ -379,7 +379,7 @@ The following variables are available in the templates: List containing names of "public" attributes in the class/module. Only available for classes and modules. - .. versionchanged:: 3.1 + .. version-changed:: 3.1 Attributes of modules are supported. @@ -388,7 +388,7 @@ The following variables are available in the templates: List containing names of "public" modules in the package. Only available for modules that are packages and the ``recursive`` option is on. - .. versionadded:: 3.1 + .. version-added:: 3.1 Additionally, the following filters are available diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst index d872181d6b5..55222c8a528 100644 --- a/doc/usage/extensions/coverage.rst +++ b/doc/usage/extensions/coverage.rst @@ -66,7 +66,7 @@ what the builder should check: or the :rst:dir:`automodule` directive provided by the :mod:`~sphinx.ext.autodoc` extension. - .. versionadded:: 7.4 + .. version-added:: 7.4 .. confval:: coverage_ignore_modules coverage_ignore_functions @@ -83,7 +83,7 @@ what the builder should check: .. _Python regular expressions: https://docs.python.org/library/re - .. versionadded:: 2.1 + .. version-added:: 2.1 .. confval:: coverage_c_path :type: :code-py:`Sequence[str]` @@ -103,7 +103,7 @@ what the builder should check: Set to ``False`` to not write headlines. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: coverage_skip_undoc_in_source :type: :code-py:`bool` @@ -111,7 +111,7 @@ what the builder should check: Skip objects that are not documented in the source with a docstring. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: coverage_show_missing_items :type: :code-py:`bool` @@ -119,7 +119,7 @@ what the builder should check: Print objects that are missing to standard output also. - .. versionadded:: 3.1 + .. version-added:: 3.1 .. confval:: coverage_statistics_to_report :type: :code-py:`bool` @@ -139,7 +139,7 @@ what the builder should check: | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+ - .. versionadded:: 7.2 + .. version-added:: 7.2 .. confval:: coverage_statistics_to_stdout :type: :code-py:`bool` @@ -159,4 +159,4 @@ what the builder should check: | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+ - .. versionadded:: 7.2 + .. version-added:: 7.2 diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst index 10e8f67dfe2..927310e59df 100644 --- a/doc/usage/extensions/doctest.rst +++ b/doc/usage/extensions/doctest.rst @@ -68,7 +68,7 @@ a comma-separated list of group names. A cleanup code block. This code is not shown in the output for other builders, but executed after the doctests of the group(s) it belongs to. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. rubric:: Options @@ -133,9 +133,9 @@ a comma-separated list of group names. ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers <440#version-specifiers>`. - .. versionadded:: 1.6 + .. version-added:: 1.6 - .. versionchanged:: 1.7 + .. version-changed:: 1.7 Supported PEP-440 operands and notations @@ -369,7 +369,7 @@ The doctest extension uses the following configuration values: given -- the default behavior of accepting this substitution is a relic of pre-Python 2.2 times. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. confval:: doctest_show_successes :type: :code-py:`bool` @@ -380,7 +380,7 @@ The doctest extension uses the following configuration values: For a project with many doctests, it may be useful to set this to ``False`` to only highlight failures. - .. versionadded:: 7.2 + .. version-added:: 7.2 .. confval:: doctest_path :type: :code-py:`Sequence[str]` @@ -397,7 +397,7 @@ The doctest extension uses the following configuration values: *every* file that is tested, and for every group. You can use this to e.g. import modules you will always need in your doctests. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. confval:: doctest_global_cleanup :type: :code-py:`str` @@ -407,7 +407,7 @@ The doctest extension uses the following configuration values: for *every* file that is tested, and for every group. You can use this to e.g. remove any temporary files that the tests leave behind. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. confval:: doctest_test_doctest_blocks :type: :code-py:`str` @@ -459,4 +459,4 @@ The doctest extension uses the following configuration values: Exit when the first failure is encountered. - .. versionadded:: 8.3 + .. version-added:: 8.3 diff --git a/doc/usage/extensions/duration.rst b/doc/usage/extensions/duration.rst index 1213811daf0..c498e0f32fb 100644 --- a/doc/usage/extensions/duration.rst +++ b/doc/usage/extensions/duration.rst @@ -4,7 +4,7 @@ .. module:: sphinx.ext.duration :synopsis: Measure durations of Sphinx processing -.. versionadded:: 2.4 +.. version-added:: 2.4 This extension measures durations of Sphinx processing and show its result at end of the build. It is useful for inspecting what document diff --git a/doc/usage/extensions/extlinks.rst b/doc/usage/extensions/extlinks.rst index 4b5fe153e62..fa1f5453127 100644 --- a/doc/usage/extensions/extlinks.rst +++ b/doc/usage/extensions/extlinks.rst @@ -5,7 +5,7 @@ :synopsis: Allow inserting external links with common base URLs easily. .. moduleauthor:: Georg Brandl -.. versionadded:: 1.0 +.. version-added:: 1.0 .. role:: code-py(code) :language: Python @@ -56,7 +56,7 @@ The extension adds a config value: that generate links, i.e. ``:issue:`this issue <123>```. In this case, the *caption* is not relevant. - .. versionchanged:: 4.0 + .. version-changed:: 4.0 Support to substitute by '%s' in the caption. @@ -72,4 +72,4 @@ The extension adds a config value: If enabled, extlinks emits a warning if a hardcoded link is replaceable by an extlink, and suggests a replacement via warning. - .. versionadded:: 4.5 + .. version-added:: 4.5 diff --git a/doc/usage/extensions/githubpages.rst b/doc/usage/extensions/githubpages.rst index 6d56a303699..3d64498c644 100644 --- a/doc/usage/extensions/githubpages.rst +++ b/doc/usage/extensions/githubpages.rst @@ -4,9 +4,9 @@ .. module:: sphinx.ext.githubpages :synopsis: Publish HTML docs in GitHub Pages -.. versionadded:: 1.4 +.. version-added:: 1.4 -.. versionchanged:: 2.0 +.. version-changed:: 2.0 Support ``CNAME`` file This extension creates ``.nojekyll`` file on generated HTML directory to publish diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index 5ac2df06e10..13c302a3197 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -6,7 +6,7 @@ .. module:: sphinx.ext.graphviz :synopsis: Support for Graphviz graphs. -.. versionadded:: 0.6 +.. version-added:: 0.6 .. role:: code-py(code) :language: Python @@ -39,7 +39,7 @@ It adds these directives: As for all file references in Sphinx, if the filename is absolute, it is taken as relative to the source directory. - .. versionchanged:: 1.1 + .. version-changed:: 1.1 Added support for external files. .. rubric:: options @@ -50,21 +50,21 @@ It adds these directives: The alternate text of the graph. By default, the graph code is used to the alternate text. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: align: alignment of the graph :type: left, center or right The horizontal alignment of the graph. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. rst:directive:option:: caption: caption of the graph :type: text The caption of the graph. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. rst:directive:option:: layout: layout type of the graph :type: text @@ -73,8 +73,8 @@ It adds these directives: graphviz commands are also allowed. By default, :confval:`graphviz_dot` is used. - .. versionadded:: 1.4 - .. versionchanged:: 2.2 + .. version-added:: 1.4 + .. version-changed:: 2.2 Renamed from ``graphviz_dot`` @@ -83,14 +83,14 @@ It adds these directives: The label of the graph. - .. versionadded:: 1.6 + .. version-added:: 1.6 .. rst:directive:option:: class: class names :type: a list of class names separated by spaces The class name of the graph. - .. versionadded:: 2.4 + .. version-added:: 2.4 .. rst:directive:: graph @@ -116,37 +116,37 @@ It adds these directives: .. rst:directive:option:: alt: alternate text :type: text - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: align: alignment of the graph :type: left, center or right - .. versionadded:: 1.5 + .. version-added:: 1.5 .. rst:directive:option:: caption: caption of the graph :type: text - .. versionadded:: 1.1 + .. version-added:: 1.1 .. rst:directive:option:: layout: layout type of the graph :type: text - .. versionadded:: 1.4 - .. versionchanged:: 2.2 + .. version-added:: 1.4 + .. version-changed:: 2.2 Renamed from ``graphviz_dot`` .. rst:directive:option:: name: label :type: text - .. versionadded:: 1.6 + .. version-added:: 1.6 .. rst:directive:option:: class: class names :type: a list of class names separated by spaces The class name of the graph. - .. versionadded:: 2.4 + .. version-added:: 2.4 .. rst:directive:: digraph @@ -168,37 +168,37 @@ It adds these directives: .. rst:directive:option:: alt: alternate text :type: text - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: align: alignment of the graph :type: left, center or right - .. versionadded:: 1.5 + .. version-added:: 1.5 .. rst:directive:option:: caption: caption of the graph :type: text - .. versionadded:: 1.1 + .. version-added:: 1.1 .. rst:directive:option:: layout: layout type of the graph :type: text - .. versionadded:: 1.4 - .. versionchanged:: 2.2 + .. version-added:: 1.4 + .. version-changed:: 2.2 Renamed from ``graphviz_dot`` .. rst:directive:option:: name: label :type: text - .. versionadded:: 1.6 + .. version-added:: 1.6 .. rst:directive:option:: class: class names :type: a list of class names separated by spaces The class name of the graph. - .. versionadded:: 2.4 + .. version-added:: 2.4 There are also these config values: @@ -244,5 +244,5 @@ There are also these config values: a -> b; } - .. versionadded:: 1.0 + .. version-added:: 1.0 Previously, output always was PNG. diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index 6bdd4e0ca69..5e2eda04566 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/doc/usage/extensions/imgconverter.rst @@ -6,7 +6,7 @@ .. module:: sphinx.ext.imgconverter :synopsis: Convert images to appropriate format for builders -.. versionadded:: 1.6 +.. version-added:: 1.6 .. role:: code-py(code) :language: Python @@ -40,7 +40,7 @@ Configuration A path to a conversion command. By default, the imgconverter finds the command from search paths. - .. versionchanged:: 3.1 + .. version-changed:: 3.1 Use :command:`magick` command by default on windows @@ -50,6 +50,6 @@ Configuration Additional command-line arguments to give to :command:`convert`, as a list. - .. versionchanged:: 3.1 + .. version-changed:: 3.1 Use ``['convert']`` by default on Windows diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst index ed977f86564..f4568034ab1 100644 --- a/doc/usage/extensions/inheritance.rst +++ b/doc/usage/extensions/inheritance.rst @@ -6,7 +6,7 @@ .. module:: sphinx.ext.inheritance_diagram :synopsis: Support for displaying inheritance diagrams via graphviz. -.. versionadded:: 0.6 +.. version-added:: 0.6 .. role:: code-py(code) :language: Python @@ -33,7 +33,7 @@ It adds this directive: only display class names, without the names of the modules that contain them. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 The value of for ``parts`` can also be negative, indicating how many parts to drop from the left. For example, if all your class names start with ``lib.``, you can give ``:parts: -1`` to remove that prefix from the @@ -44,11 +44,11 @@ It adds this directive: You can use ``caption`` option to give a caption to the diagram. - .. versionchanged:: 1.1 + .. version-changed:: 1.1 Added ``private-bases`` option; previously, all bases were always included. - .. versionchanged:: 1.5 + .. version-changed:: 1.5 Added ``caption`` option It also supports a ``top-classes`` option which requires one or more class @@ -97,13 +97,13 @@ It adds this directive: .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F :top-classes: dummy.test.B, dummy.test.C - .. versionchanged:: 1.7 + .. version-changed:: 1.7 Added ``top-classes`` option to limit the scope of inheritance graphs. .. rst:directive:option:: include-subclasses :type: no value - .. versionadded:: 8.2 + .. version-added:: 8.2 If given, any subclass of the classes will be added to the diagram too. diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst index 91de6274f36..efad06dfebe 100644 --- a/doc/usage/extensions/intersphinx.rst +++ b/doc/usage/extensions/intersphinx.rst @@ -8,7 +8,7 @@ .. index:: pair: automatic; linking -.. versionadded:: 0.5 +.. version-added:: 0.5 .. role:: code-py(code) :language: Python @@ -72,7 +72,7 @@ linking: **Format** - .. versionadded:: 1.0 + .. version-added:: 1.0 A dictionary mapping unique identifiers to a tuple ``(target, inventory)``. Each ``target`` is the base URI of a foreign Sphinx documentation set and can @@ -111,7 +111,7 @@ linking: **Multiple targets for the inventory** - .. versionadded:: 1.3 + .. version-added:: 1.3 Alternative files can be specified for each inventory. One can give a tuple for the second inventory tuple item as shown in the following @@ -183,9 +183,9 @@ linking: :type: :code-py:`Sequence[str]` :default: :code-py:`['std:doc']` - .. versionadded:: 4.3 + .. version-added:: 4.3 - .. versionchanged:: 5.0 + .. version-changed:: 5.0 Changed default value from an empty list to ``['std:doc']``. @@ -219,7 +219,7 @@ The Intersphinx extension provides the following role. .. rst:role:: external - .. versionadded:: 4.4 + .. version-added:: 4.4 Use Intersphinx to perform lookup only in external projects, and not the current project. Intersphinx still needs to know the type of object you diff --git a/doc/usage/extensions/linkcode.rst b/doc/usage/extensions/linkcode.rst index fb05464a5e9..2c4401d3a30 100644 --- a/doc/usage/extensions/linkcode.rst +++ b/doc/usage/extensions/linkcode.rst @@ -5,7 +5,7 @@ :synopsis: Add external links to source code. .. moduleauthor:: Pauli Virtanen -.. versionadded:: 1.2 +.. version-added:: 1.2 .. role:: code-py(code) :language: Python diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 6fa8ab851f8..e4b8d78144f 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -8,8 +8,8 @@ Math support for HTML outputs in Sphinx .. module:: sphinx.ext.mathbase :synopsis: Common math support for imgmath and mathjax / jsmath. -.. versionadded:: 0.5 -.. versionchanged:: 1.8 +.. version-added:: 0.5 +.. version-changed:: 1.8 Math support for non-HTML builders is integrated to sphinx-core. So mathbase extension is no longer needed. @@ -27,7 +27,7 @@ reStructuredText math :rst:dir:`directive ` and :rst:role:`role `. .. module:: sphinx.ext.imgmath :synopsis: Render math as PNG or SVG images. -.. versionadded:: 1.4 +.. version-added:: 1.4 This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG images. This of course means that the computer where the docs are built must @@ -57,7 +57,7 @@ are built: ``preview-latex-style`` on Ubuntu xenial). Therefore, the default for this option is ``False`` but it is strongly recommended to set it to ``True``. - .. versionchanged:: 2.2 + .. version-changed:: 2.2 This option can be used with the ``'svg'`` :confval:`imgmath_image_format`. @@ -112,7 +112,7 @@ are built: ``'latexmk'`` (or a full path to it) as this Perl script reliably chooses dynamically how many latex runs are needed. - .. versionchanged:: 6.2.0 + .. version-changed:: 6.2.0 Using ``'xelatex'`` (or a full path to it) is now supported. But you must then add ``'-no-pdf'`` to the :confval:`imgmath_latex_args` list of @@ -188,7 +188,7 @@ are built: If true, encode LaTeX output images within HTML files (base64 encoded) and do not save separate png/svg files to disk. - .. versionadded:: 5.2 + .. version-added:: 5.2 :mod:`sphinx.ext.mathjax` -- Render math via JavaScript ------------------------------------------------------- @@ -203,7 +203,7 @@ are built: or update your configuration options for version 3 (see :confval:`mathjax3_config`). -.. versionadded:: 1.1 +.. version-added:: 1.1 This extension puts math as-is into the HTML files. The JavaScript package MathJax_ is then loaded and transforms the LaTeX markup to readable math live in @@ -256,9 +256,9 @@ Sphinx but is set to automatically include it from a third-party site. 'integrity': 'sha384-......', } - .. versionadded:: 1.8 + .. version-added:: 1.8 - .. versionchanged:: 4.4.1 + .. version-changed:: 4.4.1 Allow to change the loading method (async or defer) of MathJax if "async" or "defer" key is set. @@ -274,7 +274,7 @@ Sphinx but is set to automatically include it from a third-party site. __ https://docs.mathjax.org/en/latest/web/configuration.html#configuration - .. versionadded:: 4.0 + .. version-added:: 4.0 .. confval:: mathjax2_config :type: :code-py:`dict[str, Any] | None` @@ -295,7 +295,7 @@ Sphinx but is set to automatically include it from a third-party site. 'jax': ['input/TeX', 'output/HTML-CSS'], } - .. versionadded:: 4.0 + .. version-added:: 4.0 :confval:`mathjax_config` has been renamed to :confval:`mathjax2_config`. @@ -311,9 +311,9 @@ Sphinx but is set to automatically include it from a third-party site. __ https://docs.mathjax.org/en/latest/web/ configuration.html#converting-your-v2-configuration-to-v3 - .. versionadded:: 1.8 + .. version-added:: 1.8 - .. versionchanged:: 4.0 + .. version-changed:: 4.0 This has been renamed to :confval:`mathjax2_config`. :confval:`mathjax_config` is still supported for backwards compatibility. diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index 469e3fddc89..976b467b77a 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -6,7 +6,7 @@ .. moduleauthor:: Rob Ruana -.. versionadded:: 1.3 +.. version-added:: 1.3 .. role:: code-py(code) :language: Python @@ -566,8 +566,8 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``: True to convert the type definitions in the docstrings as references. - .. versionadded:: 3.2.1 - .. versionchanged:: 3.5 + .. version-added:: 3.2.1 + .. version-changed:: 3.5 Do preprocess the Google style docstrings also. @@ -607,7 +607,7 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``: :param arg2: Description of `arg2` :type arg2: :term:`dict-like ` - .. versionadded:: 3.2 + .. version-added:: 3.2 .. confval:: napoleon_attr_annotations :type: :code-py:`bool` @@ -617,7 +617,7 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``: If an attribute is documented in the docstring without a type and has an annotation in the class body, that type is used. - .. versionadded:: 3.4 + .. version-added:: 3.4 .. confval:: napoleon_custom_sections :type: :code-py:`Sequence[str | tuple[str, str]] | None` @@ -640,6 +640,6 @@ sure that "sphinx.ext.napoleon" is enabled in ``conf.py``: second entry value is "params_style" or "returns_style", the custom section will be displayed like the parameters section or returns section. - .. versionadded:: 1.8 - .. versionchanged:: 3.5 + .. version-added:: 1.8 + .. version-changed:: 3.5 Support ``params_style`` and ``returns_style`` diff --git a/doc/usage/extensions/todo.rst b/doc/usage/extensions/todo.rst index cdfbccb055f..fefa971d00a 100644 --- a/doc/usage/extensions/todo.rst +++ b/doc/usage/extensions/todo.rst @@ -5,7 +5,7 @@ :synopsis: Allow inserting todo items into documents. .. moduleauthor:: Daniel Bültmann -.. versionadded:: 0.5 +.. version-added:: 0.5 .. role:: code-py(code) :language: Python @@ -19,7 +19,7 @@ There are two additional directives when using this extension: It will only show up in the output if :confval:`todo_include_todos` is ``True``. - .. versionadded:: 1.3.2 + .. version-added:: 1.3.2 This directive supports an ``class`` option that determines the class attribute for HTML output. If not given, the class defaults to ``admonition-todo``. @@ -49,7 +49,7 @@ Configuration If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. confval:: todo_link_only :type: :code-py:`bool` @@ -58,13 +58,13 @@ Configuration If this is ``True``, :rst:dir:`todolist` produce output without file path and line. - .. versionadded:: 1.4 + .. version-added:: 1.4 autodoc provides the following an additional event: .. event:: todo-defined (app, node) - .. versionadded:: 1.5 + .. version-added:: 1.5 Emitted when a todo is defined. *node* is the defined ``sphinx.ext.todo.todo_node`` node. diff --git a/doc/usage/extensions/viewcode.rst b/doc/usage/extensions/viewcode.rst index aa5a9368f3d..c6ce3848024 100644 --- a/doc/usage/extensions/viewcode.rst +++ b/doc/usage/extensions/viewcode.rst @@ -5,7 +5,7 @@ :synopsis: Add links to a highlighted version of the source code. .. moduleauthor:: Georg Brandl -.. versionadded:: 1.0 +.. version-added:: 1.0 .. role:: code-py(code) :language: Python @@ -50,9 +50,9 @@ Configuration :event:`viewcode-follow-imported` event to resolve the name of the module by other extensions. - .. versionadded:: 1.3 + .. version-added:: 1.3 - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Renamed from ``viewcode_import`` to ``viewcode_follow_imported_members``. .. confval:: viewcode_enable_epub @@ -67,7 +67,7 @@ Configuration epub as same as 1.4.x, you should set ``True``, but epub format checker's score becomes worse. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. warning:: @@ -84,11 +84,11 @@ Configuration If set to ``True``, inline line numbers will be added to the highlighted code. - .. versionadded:: 7.2 + .. version-added:: 7.2 .. event:: viewcode-find-source (app, modname) - .. versionadded:: 1.8 + .. version-added:: 1.8 Find the source code for a module. An event handler for this event should return @@ -102,7 +102,7 @@ Configuration .. event:: viewcode-follow-imported (app, modname, attribute) - .. versionadded:: 1.8 + .. version-added:: 1.8 Find the name of the original module for an attribute. diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 571d3c798bc..ce021b59a15 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -130,7 +130,7 @@ Cross-referencing arbitrary locations Cross-referencing documents --------------------------- -.. versionadded:: 0.6 +.. version-added:: 0.6 There is also a way to directly link to documents: @@ -149,7 +149,7 @@ There is also a way to directly link to documents: Referencing downloadable files ------------------------------ -.. versionadded:: 0.6 +.. version-added:: 0.6 .. rst:role:: download @@ -183,9 +183,9 @@ Referencing downloadable files Cross-referencing figures by figure number ------------------------------------------ -.. versionadded:: 1.3 +.. version-added:: 1.3 -.. versionchanged:: 1.5 +.. version-changed:: 1.5 :rst:role:`numref` role can also refer sections. And :rst:role:`numref` allows ``{name}`` for the link text. @@ -265,7 +265,7 @@ Cross-referencing anything .. rst:role:: any - .. versionadded:: 1.3 + .. version-added:: 1.3 This convenience role tries to do its best to find a valid target for its reference text. diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 8f408f45e38..18b8723e080 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -514,13 +514,13 @@ latter. Supported image types and choosing priority are defined at Note that image file names should not contain spaces. -.. versionchanged:: 0.4 +.. version-changed:: 0.4 Added the support for file names ending in an asterisk. -.. versionchanged:: 0.6 +.. version-changed:: 0.6 Image paths can now be absolute. -.. versionchanged:: 1.5 +.. version-changed:: 1.5 latex target supports pixels (default is ``96px=1in``). diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index d6688ad53dd..fe6d4203385 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -114,7 +114,7 @@ The ``toctree`` directive is the central element. tree hierarchy. It can be used as the documentation's main page, or as a "full table of contents" if you don't give a ``:maxdepth:`` option. - .. versionchanged:: 0.6 + .. version-changed:: 0.6 Added support for external links and "self" references. .. rubric:: Options @@ -131,7 +131,7 @@ The ``toctree`` directive is the central element. .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes - .. versionadded:: 7.4 + .. version-added:: 7.4 .. rst:directive:option:: name: label :type: text @@ -145,7 +145,7 @@ The ``toctree`` directive is the central element. foo - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rst:directive:option:: caption :type: text @@ -158,7 +158,7 @@ The ``toctree`` directive is the central element. foo - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rst:directive:option:: numbered numbered: depth @@ -180,9 +180,9 @@ The ``toctree`` directive is the central element. Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to ``numbered``. - .. versionadded:: 0.6 + .. version-added:: 0.6 - .. versionchanged:: 1.1 + .. version-changed:: 1.1 Added the numeric *depth* argument. .. rst:directive:option:: titlesonly @@ -196,7 +196,7 @@ The ``toctree`` directive is the central element. foo bar - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: glob @@ -216,14 +216,14 @@ The ``toctree`` directive is the central element. then all documents in the ``recipe`` folder, then all remaining documents (except the one containing the directive, of course.) [#]_ - .. versionadded:: 0.3 + .. version-added:: 0.3 .. rst:directive:option:: reversed Reverse the order of the entries in the list. This is particularly useful when using the ``:glob:`` option. - .. versionadded:: 1.5 + .. version-added:: 1.5 .. rst:directive:option:: hidden @@ -234,7 +234,7 @@ The ``toctree`` directive is the central element. e.g. through manual links, HTML sidebar navigation, or if you use the ``:includehidden:`` option on the top-level toctree. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:directive:option:: includehidden @@ -244,7 +244,7 @@ The ``toctree`` directive is the central element. with the ``:hidden:`` option. The top-level toctree with ``:includehidden:`` will then include their entries. - .. versionadded:: 1.2 + .. version-added:: 1.2 Special names @@ -484,7 +484,7 @@ and the generic :rst:dir:`admonition` directive. .. rubric:: Collapsible text -.. versionadded:: 8.2 +.. version-added:: 8.2 Each admonition directive supports a ``:collapsible:`` option, to make the content of the admonition collapsible @@ -663,7 +663,7 @@ Presentational .. rst:directive:option:: heading-level: n :type: number from 1 to 6 - .. versionadded:: 7.4.1 + .. version-added:: 7.4.1 Use this option to specify the heading level of the rubric. In this case the rubric will be rendered as ``

`` to ``

`` for HTML output, @@ -703,7 +703,7 @@ Presentational * displayed * horizontally - .. versionadded:: 0.6 + .. version-added:: 0.6 .. _code-examples: @@ -797,7 +797,7 @@ __ https://pygments.org/docs/lexers If given, minor errors on highlighting are ignored. - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rst:directive:: .. code-block:: [language] .. sourcecode:: [language] @@ -817,7 +817,7 @@ __ https://pygments.org/docs/lexers *inline* within other text, rather than as a separate block, you can use the :rst:role:`code` role instead. - .. versionchanged:: 2.0 + .. version-changed:: 2.0 The ``language`` argument becomes optional. .. rubric:: Options @@ -843,7 +843,7 @@ __ https://pygments.org/docs/lexers Some more Ruby code, with line numbering starting at 10. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rst:directive:option:: emphasize-lines: line numbers :type: comma separated numbers @@ -859,8 +859,8 @@ __ https://pygments.org/docs/lexers print('This one is not...') print('...but this one is.') - .. versionadded:: 1.1 - .. versionchanged:: 1.6.6 + .. version-added:: 1.1 + .. version-changed:: 1.6.6 LaTeX supports the ``emphasize-lines`` option. .. rst:directive:option:: force @@ -868,14 +868,14 @@ __ https://pygments.org/docs/lexers Ignore minor errors on highlighting. - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rst:directive:option:: caption: caption of code block :type: text Set a caption to the code block. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rst:directive:option:: name: a label for hyperlink :type: text @@ -903,7 +903,7 @@ __ https://pygments.org/docs/lexers See :ref:`this code snippet ` for an example. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rst:directive:option:: class: class names :type: a list of class names separated by spaces @@ -911,7 +911,7 @@ __ https://pygments.org/docs/lexers Assign `class attributes`_. This is a :dudir:`common option `. - .. versionadded:: 1.4 + .. version-added:: 1.4 .. rst:directive:option:: dedent: number :type: number or no value @@ -926,8 +926,8 @@ __ https://pygments.org/docs/lexers some ruby code - .. versionadded:: 1.3 - .. versionchanged:: 3.5 + .. version-added:: 1.3 + .. version-changed:: 3.5 Support automatic dedent. .. rst:directive:: .. literalinclude:: filename @@ -955,7 +955,7 @@ __ https://pygments.org/docs/lexers .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes - .. versionadded:: 1.4 + .. version-added:: 1.4 .. rst:directive:option:: name: label :type: text @@ -963,7 +963,7 @@ __ https://pygments.org/docs/lexers An implicit target name that can be referenced using :rst:role:`ref`. This is a :dudir:`common option `. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rst:directive:option:: caption: caption :type: text @@ -971,7 +971,7 @@ __ https://pygments.org/docs/lexers Add a caption above the included content. If no argument is given, the filename is used as the caption. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rubric:: Options for formatting @@ -983,8 +983,8 @@ __ https://pygments.org/docs/lexers When no argument given, all common leading indentation is removed (using :func:`textwrap.dedent`). - .. versionadded:: 1.3 - .. versionchanged:: 3.5 + .. version-added:: 1.3 + .. version-changed:: 3.5 Support automatic dedent. .. rst:directive:option:: tab-width: N @@ -992,7 +992,7 @@ __ https://pygments.org/docs/lexers Expand tabs to N spaces. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: encoding :type: text @@ -1006,7 +1006,7 @@ __ https://pygments.org/docs/lexers .. literalinclude:: example.txt :encoding: latin-1 - .. versionadded:: 0.4.3 + .. version-added:: 0.4.3 .. rst:directive:option:: linenos :type: no value @@ -1026,7 +1026,7 @@ __ https://pygments.org/docs/lexers When including only parts of a file and show the original line numbers. This is only allowed only when the selection consists of contiguous lines. - .. versionadded:: 1.3 + .. version-added:: 1.3 .. rst:directive:option:: emphasize-lines: line numbers :type: comma separated numbers @@ -1053,7 +1053,7 @@ __ https://pygments.org/docs/lexers Ignore minor errors in highlighting. - .. versionadded:: 2.1 + .. version-added:: 2.1 .. rubric:: Options for selecting the content to include @@ -1067,7 +1067,7 @@ __ https://pygments.org/docs/lexers .. literalinclude:: example.py :pyobject: Timer.start - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:directive:option:: lines: line numbers :type: comma separated numbers @@ -1079,7 +1079,7 @@ __ https://pygments.org/docs/lexers This includes line 1, line 3, lines 5 to 10, and line 20 to the end. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:directive:option:: start-at: text start-after: text @@ -1103,9 +1103,9 @@ __ https://pygments.org/docs/lexers that contains the option string (``end-at`` will keep the line and ``end-before`` skip the first line). - .. versionadded:: 0.6 + .. version-added:: 0.6 Added the ``start-after`` and ``end-before`` options. - .. versionadded:: 1.5 + .. version-added:: 1.5 Added the ``start-at``, and ``end-at`` options. .. tip:: @@ -1146,7 +1146,7 @@ __ https://pygments.org/docs/lexers This can be useful for example when highlighting PHP code that doesn't include the ```` markers. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: append: line :type: text @@ -1155,7 +1155,7 @@ __ https://pygments.org/docs/lexers This can be useful for example when highlighting PHP code that doesn't include the ```` markers. - .. versionadded:: 1.0 + .. version-added:: 1.0 .. rst:directive:option:: diff: filename @@ -1170,12 +1170,12 @@ __ https://pygments.org/docs/lexers This shows the diff between ``example.txt`` and ``example.txt.orig`` with unified diff format. - .. versionadded:: 1.3 + .. version-added:: 1.3 - .. versionchanged:: 0.6 + .. version-changed:: 0.6 Added support for absolute filenames. - .. versionchanged:: 1.6 + .. version-changed:: 1.6 With both ``start-after`` and ``lines`` in use, the first line as per ``start-after`` is considered to be with line number ``1`` for ``lines``. @@ -1234,10 +1234,10 @@ Glossary categorized in "key" group. - .. versionchanged:: 1.1 + .. version-changed:: 1.1 Now supports multiple terms and inline markup in terms. - .. versionchanged:: 1.4 + .. version-changed:: 1.4 Index key for glossary term should be considered *experimental*. @@ -1247,9 +1247,9 @@ Glossary Sort the entries alphabetically. - .. versionadded:: 0.6 + .. version-added:: 0.6 - .. versionchanged:: 4.4 + .. version-changed:: 4.4 In internationalized documentation, sort according to translated terms. @@ -1375,7 +1375,7 @@ mainly contained in information units, such as the language reference. .. deprecated:: 1.0 These Python-specific entry types are deprecated. - .. versionchanged:: 7.1 + .. version-changed:: 7.1 Removal version set to Sphinx 9.0. Using these entry types will now emit warnings with the ``index`` category. @@ -1398,7 +1398,7 @@ mainly contained in information units, such as the language reference. This creates four index entries. - .. versionchanged:: 1.1 + .. version-changed:: 1.1 Added ``see`` and ``seealso`` types, as well as marking main entries. .. rubric:: Options @@ -1412,7 +1412,7 @@ mainly contained in information units, such as the language reference. .. index:: Python :name: py-index - .. versionadded:: 3.0 + .. version-added:: 3.0 .. rst:role:: index @@ -1429,7 +1429,7 @@ mainly contained in information units, such as the language reference. This is a normal reStructuredText :index:`paragraph` that contains several :index:`index entries `. - .. versionadded:: 1.1 + .. version-added:: 1.1 .. _tags: @@ -1467,8 +1467,8 @@ Including content based on tags uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_`` and, except for the first character, the digits ``0`` through ``9``. - .. versionadded:: 0.6 - .. versionchanged:: 1.2 + .. version-added:: 0.6 + .. version-changed:: 1.2 Added the name of the builder and the prefixes. .. warning:: @@ -1494,12 +1494,12 @@ The :dudir:`table` directive serves as optional wrapper of the *grid* and They work fine in HTML output, but rendering tables to LaTeX is complex. Check the :confval:`latex_table_style`. -.. versionchanged:: 1.6 +.. version-changed:: 1.6 Merged cells (multi-row, multi-column, both) from grid tables containing complex contents such as multiple paragraphs, blockquotes, lists, literal blocks, will render correctly to LaTeX output. -.. versionchanged:: 8.3.0 +.. version-changed:: 8.3.0 The partial support of the LaTeX builder for nesting a table in another has been extended. Formerly Sphinx would raise an error if ``longtable`` class was specified @@ -1518,7 +1518,7 @@ Check the :confval:`latex_table_style`. .. _wiki page: https://en.wikibooks.org/wiki/LaTeX/Tables - .. versionadded:: 0.3 + .. version-added:: 0.3 Sphinx renders tables with at most 30 rows using ``tabulary`` (or ``tabular`` if at least one cell contains either a code-block or a nested @@ -1579,14 +1579,14 @@ Check the :confval:`latex_table_style`. is a decimal: for example ``\Y{0.2}`` means that the column will occupy ``0.2`` times the line width. -.. versionchanged:: 1.6 +.. version-changed:: 1.6 Sphinx uses ``J`` (justified) by default with ``tabulary``, not ``L`` (flushed-left). To revert, include ``\newcolumntype{T}{L}`` in the LaTeX preamble, as in fact Sphinx uses ``T`` and sets it by default to be an alias of ``J``. -.. versionchanged:: 8.3.0 +.. version-changed:: 8.3.0 Formerly, Sphinx did not use ``tabulary`` if the table had at least one cell containing "problematic" elements such as lists, object descriptions, @@ -1687,7 +1687,7 @@ or use Python raw strings (``r"raw"``). f(x) & = & x^2 + 2xy + y^2 \end{eqnarray} - .. versionchanged:: 8.2 + .. version-changed:: 8.2 The directive option ``:nowrap:`` was renamed to ``:no-wrap:``. diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst index b85d94520d1..6aa31967814 100644 --- a/doc/usage/restructuredtext/field-lists.rst +++ b/doc/usage/restructuredtext/field-lists.rst @@ -52,7 +52,7 @@ At the moment, these metadata fields are recognized: affect the depth of the *global* toctree. So this does not change the sidebar of themes that use the global toctree. - .. versionadded:: 0.4 + .. version-added:: 0.4 ``nocomments`` If set, the web application won't display a comment form for a page @@ -66,7 +66,7 @@ At the moment, these metadata fields are recognized: :orphan: - .. versionadded:: 1.0 + .. version-added:: 1.0 ``no-search`` Disable full text search for this document. @@ -80,9 +80,9 @@ At the moment, these metadata fields are recognized: meaning that object search will still be available even if ``:no-search:`` is set. - .. versionadded:: 3.0 + .. version-added:: 3.0 - .. versionchanged:: 7.3 + .. version-changed:: 7.3 The file-wide metadata option ``:nosearch:`` was renamed to ``:no-search:``. diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index bf9f02945f5..940f686379d 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -100,7 +100,7 @@ different style: For example: ``:abbr:`LIFO (last-in, first-out)``` displays :abbr:`LIFO (last-in, first-out)`. - .. versionadded:: 0.6 + .. version-added:: 0.6 .. rst:role:: command @@ -136,7 +136,7 @@ different style: labels, window titles, field names, menu and menu selection names, and even values in selection lists. - .. versionchanged:: 1.0 + .. version-changed:: 1.0 An accelerator key for the GUI label can be included using an ampersand; this will be stripped and displayed underlined in the output (for example: ``:guilabel:`&Cancel``` displays :guilabel:`&Cancel`). To include a literal @@ -175,7 +175,7 @@ different style: ``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an external site rendering the manpage if :confval:`manpages_url` is defined. - .. versionchanged:: 7.3 + .. version-changed:: 7.3 Allow specifying a target with ``<>``, like hyperlinks. For example, ``:manpage:`blah ``` displays :manpage:`blah `. @@ -239,7 +239,7 @@ different style: If you don't need the "variable part" indication, use the standard :rst:role:`code` role instead. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Allowed to escape curly braces with double backslash. For example, in ``:samp:`print(f"answer=\\{1+{variable}*2\\}")```, the part ``variable`` would be emphasized and the escaped curly braces would be displayed: @@ -261,7 +261,7 @@ The following roles generate external links: For example: :cve:`2020-10735` - .. versionadded:: 8.1 + .. version-added:: 8.1 .. rst:role:: cwe @@ -275,7 +275,7 @@ The following roles generate external links: For example: :cwe:`787` - .. versionadded:: 8.1 + .. version-added:: 8.1 .. rst:role:: pep diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst index a596acfe0eb..5f8c5f8cd44 100644 --- a/doc/usage/theming.rst +++ b/doc/usage/theming.rst @@ -16,7 +16,7 @@ Builders Themes ------ -.. versionadded:: 0.6 +.. version-added:: 0.6 .. note:: @@ -176,7 +176,7 @@ These themes are: (see :confval:`html_sidebars`). Defaults to ``True``. - .. versionadded:: 3.1 + .. version-added:: 3.1 - **globaltoc_includehidden** (true or false): Show even those subsections in ``globaltoc.html`` (see :confval:`html_sidebars`) @@ -184,13 +184,13 @@ These themes are: :rst:dir:`toctree` directive. Defaults to ``False``. - .. versionadded:: 3.1 + .. version-added:: 3.1 - **globaltoc_maxdepth** (int): The maximum depth of the toctree in ``globaltoc.html`` (see :confval:`html_sidebars`). Set it to -1 to allow unlimited depth. Defaults to the max depth selected in the toctree directive. - .. versionadded:: 3.2 + .. version-added:: 3.2 **alabaster** `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz @@ -337,10 +337,10 @@ These themes are: - **rightsidebar** (true or false): Put the sidebar on the right side. Defaults to ``False``. -.. versionadded:: 1.3 +.. version-added:: 1.3 'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme. -.. versionchanged:: 1.3 +.. version-changed:: 1.3 The 'default' theme has been renamed to 'classic'. 'default' is still available, however it will emit a notice that it is an alias for the new 'alabaster' theme. diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 79df3e09df3..3303cc4cb17 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -20,7 +20,7 @@ #: ``(1, 2, 1, 'beta', 3)``. The fourth element can be one of: ``alpha``, #: ``beta``, ``rc``, ``final``. ``final`` always has 0 as the last element. #: -#: .. versionadded:: 1.2 +#: .. version-added:: 1.2 #: Before version 1.2, check the string ``sphinx.__version__``. version_info: Final = (8, 3, 0, 'beta', 0) diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 4ce85dabcf2..4023414069a 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -544,7 +544,7 @@ class pending_xref_condition(nodes.Inline, nodes.TextElement): Additionally, as a recommended condition name, ``condition="resolved"`` represents a resolution success in the intersphinx module. - .. versionadded:: 4.0 + .. version-added:: 4.0 """ diff --git a/sphinx/application.py b/sphinx/application.py index 8538ce72e79..d850da0d853 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -507,8 +507,8 @@ def require_sphinx(version: tuple[int, int] | str) -> None: :param version: The required version in the form of ``major.minor`` or ``(major, minor)``. - .. versionadded:: 1.0 - .. versionchanged:: 7.1 + .. version-added:: 1.0 + .. version-changed:: 7.1 Type of *version* now allows ``(major, minor)`` form. """ if isinstance(version, tuple): @@ -821,7 +821,7 @@ def connect( in order of *priority* (ascending). :return: A listener ID. It can be used for :meth:`disconnect`. - .. versionchanged:: 3.0 + .. version-changed:: 3.0 Support *priority* """ @@ -858,7 +858,7 @@ def emit( :param args: The arguments for the event :param allowed_exceptions: The list of exceptions that are allowed in the callbacks - .. versionchanged:: 3.1 + .. version-changed:: 3.1 Added *allowed_exceptions* to specify path-through exceptions """ @@ -878,8 +878,8 @@ def emit_firstresult( :param args: The arguments for the event :param allowed_exceptions: The list of exceptions that are allowed in the callbacks - .. versionadded:: 0.5 - .. versionchanged:: 3.1 + .. version-added:: 0.5 + .. version-changed:: 3.1 Added *allowed_exceptions* to specify path-through exceptions """ @@ -896,7 +896,7 @@ def add_builder(self, builder: type[Builder], override: bool = False) -> None: :param override: If true, install the builder forcedly even if another builder is already installed as the same name - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_builder(builder, override=override) @@ -931,18 +931,18 @@ def add_config_value( value. :param description: A short description of the configuration value. - .. versionchanged:: 0.4 + .. version-changed:: 0.4 If the *default* value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values. - .. versionchanged:: 0.6 + .. version-changed:: 0.6 Changed *rebuild* from a simple boolean (equivalent to ``''`` or ``'env'``) to a string. However, booleans are still accepted and converted internally. - .. versionadded:: 7.4 + .. version-added:: 7.4 The *description* parameter. """ logger.debug('[app] adding config value: %r', (name, default, rebuild, types)) @@ -981,8 +981,8 @@ def set_translator( :param override: If true, install the translator forcedly even if another translator is already installed as the same name - .. versionadded:: 1.3 - .. versionchanged:: 1.8 + .. version-added:: 1.3 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_translator(name, translator_class, override=override) @@ -1025,7 +1025,7 @@ def depart_math_html(self, node): Obviously, translators for which you don't specify visitor methods will choke on the node when encountered in a document to translate. - .. versionchanged:: 0.5 + .. version-changed:: 0.5 Added the support for keyword arguments giving visit functions. """ logger.debug('[app] adding node: %r', (node, kwargs)) @@ -1071,7 +1071,7 @@ def add_enumerable_node( :param override: If true, install the node forcedly even if another node is already installed as the same name - .. versionadded:: 1.4 + .. version-added:: 1.4 """ self.registry.add_enumerable_node( node, figtype, title_getter, override=override @@ -1115,11 +1115,11 @@ def setup(app): For more details, see `the Docutils docs `__ . - .. versionchanged:: 0.6 + .. version-changed:: 0.6 Docutils 0.5-style directive classes are now supported. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Docutils 0.4-style (function based) directives support is deprecated. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Add *override* keyword. """ logger.debug('[app] adding directive: %r', (name, cls)) @@ -1145,7 +1145,7 @@ def add_role(self, name: str, role: Any, override: bool = False) -> None: For more details about role functions, see `the Docutils docs `__ . - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Add *override* keyword. """ logger.debug('[app] adding role: %r', (name, role)) @@ -1170,8 +1170,8 @@ def add_generic_role( is already installed as the same name If true, unconditionally install the role. - .. versionadded:: 0.6 - .. versionchanged:: 1.8 + .. version-added:: 0.6 + .. version-changed:: 1.8 Add *override* keyword. """ # Don't use ``roles.register_generic_role`` because it uses @@ -1195,8 +1195,8 @@ def add_domain(self, domain: type[Domain], override: bool = False) -> None: is already installed as the same name If true, unconditionally install the domain. - .. versionadded:: 1.0 - .. versionchanged:: 1.8 + .. version-added:: 1.0 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_domain(domain, override=override) @@ -1216,8 +1216,8 @@ def add_directive_to_domain( is already installed as the same name If true, unconditionally install the directive. - .. versionadded:: 1.0 - .. versionchanged:: 1.8 + .. version-added:: 1.0 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_directive_to_domain(domain, name, cls, override=override) @@ -1241,8 +1241,8 @@ def add_role_to_domain( is already installed as the same name If true, unconditionally install the role. - .. versionadded:: 1.0 - .. versionchanged:: 1.8 + .. version-added:: 1.0 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_role_to_domain(domain, name, role, override=override) @@ -1260,8 +1260,8 @@ def add_index_to_domain( is already installed as the same name If true, unconditionally install the index. - .. versionadded:: 1.0 - .. versionchanged:: 1.8 + .. version-added:: 1.0 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_index_to_domain(domain, index) @@ -1334,7 +1334,7 @@ def add_object_type( If *override* is True, the given object_type is forcedly installed even if an object_type having the same name is already installed. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_object_type( @@ -1389,7 +1389,7 @@ def add_crossref_type( is already installed as the same name If true, unconditionally install the cross-reference type. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_crossref_type( @@ -1499,15 +1499,15 @@ def add_js_file( A JavaScript file can be added to the specific HTML page when an extension calls this method on :event:`html-page-context` event. - .. versionadded:: 0.5 + .. version-added:: 0.5 - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Renamed from ``app.add_javascript()``. And it allows keyword arguments as attributes of script tag. - .. versionchanged:: 3.5 + .. version-changed:: 3.5 Take priority argument. Allow to add a JavaScript file to the specific page. - .. versionchanged:: 4.4 + .. version-changed:: 4.4 Take loading_method argument. Allow to change the loading method of the JavaScript file. """ @@ -1564,20 +1564,20 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non A CSS file can be added to the specific HTML page when an extension calls this method on :event:`html-page-context` event. - .. versionadded:: 1.0 + .. version-added:: 1.0 - .. versionchanged:: 1.6 + .. version-changed:: 1.6 Optional ``alternate`` and/or ``title`` attributes can be supplied with the arguments *alternate* (a Boolean) and *title* (a string). The default is no title and *alternate* = ``False``. For more information, refer to the `documentation `__. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Renamed from ``app.add_stylesheet()``. And it allows keyword arguments as attributes of link tag. - .. versionchanged:: 3.5 + .. version-changed:: 3.5 Take priority argument. Allow to add a CSS file to the specific page. """ logger.debug('[app] adding stylesheet: %r', filename) @@ -1604,8 +1604,8 @@ def add_latex_package( app.add_latex_package('mypackage', 'foo,bar') # => \usepackage[foo,bar]{mypackage} - .. versionadded:: 1.3 - .. versionadded:: 3.1 + .. version-added:: 1.3 + .. version-added:: 3.1 *after_hyperref* option. """ @@ -1616,10 +1616,10 @@ def add_lexer(self, alias: str, lexer: type[Lexer]) -> None: Use *lexer* to highlight code blocks with the given language *alias*. - .. versionadded:: 0.6 - .. versionchanged:: 2.1 + .. version-added:: 0.6 + .. version-changed:: 2.1 Take a lexer class as an argument. - .. versionchanged:: 4.0 + .. version-changed:: 4.0 Removed support for lexer instances as an argument. """ logger.debug('[app] adding lexer: %r', (alias, lexer)) @@ -1639,8 +1639,8 @@ def add_autodocumenter(self, cls: type[Documenter], override: bool = False) -> N See :ref:`autodoc_ext_tutorial`. - .. versionadded:: 0.6 - .. versionchanged:: 2.2 + .. version-added:: 0.6 + .. version-changed:: 2.2 Add *override* keyword. """ logger.debug('[app] adding autodocumenter: %r', cls) @@ -1660,7 +1660,7 @@ def add_autodoc_attrgetter( get an attribute of a type are then handled by this function instead of :func:`getattr`. - .. versionadded:: 0.6 + .. version-added:: 0.6 """ logger.debug('[app] adding autodoc attrgetter: %r', (typ, getter)) self.registry.add_autodoc_attrgetter(typ, getter) @@ -1674,7 +1674,7 @@ def add_search_language(self, cls: type[SearchLanguage]) -> None: attribute that indicates the language it should be used for. See :confval:`html_search_language`. - .. versionadded:: 1.1 + .. version-added:: 1.1 """ logger.debug('[app] adding search language: %r', cls) from sphinx.search import languages @@ -1693,7 +1693,7 @@ def add_source_suffix( is already installed. If true, unconditionally install the suffix. - .. versionadded:: 1.8 + .. version-added:: 1.8 """ self.registry.add_source_suffix(suffix, filetype, override=override) @@ -1704,11 +1704,11 @@ def add_source_parser(self, parser: type[Parser], override: bool = False) -> Non is already installed for the same suffix. If true, unconditionally install the parser. - .. versionadded:: 1.4 - .. versionchanged:: 1.8 + .. version-added:: 1.4 + .. version-changed:: 1.8 *suffix* argument is deprecated. It only accepts *parser* argument. Use :meth:`add_source_suffix` API to register suffix instead. - .. versionchanged:: 1.8 + .. version-changed:: 1.8 Add *override* keyword. """ self.registry.add_source_parser(parser, override=override) @@ -1718,7 +1718,7 @@ def add_env_collector(self, collector: type[EnvironmentCollector]) -> None: Refer to :ref:`collector-api`. - .. versionadded:: 1.6 + .. version-added:: 1.6 """ logger.debug('[app] adding environment collector: %r', collector) collector().enable(self) @@ -1729,7 +1729,7 @@ def add_html_theme(self, name: str, theme_path: str | os.PathLike[str]) -> None: The *name* is a name of theme, and *theme_path* is a full path to the theme (refs: :ref:`distribute-your-theme`). - .. versionadded:: 1.6 + .. version-added:: 1.6 """ logger.debug('[app] adding HTML theme: %r, %r', name, theme_path) self.registry.add_html_theme(name, theme_path) @@ -1748,7 +1748,7 @@ def add_html_math_renderer( block math node (``nodes.math_block``). Regarding visitor functions, see :meth:`add_node` for details. - .. versionadded:: 1.8 + .. version-added:: 1.8 """ self.registry.add_html_math_renderer(name, inline_renderers, block_renderers) @@ -1763,7 +1763,7 @@ def add_message_catalog( For more details, see :func:`sphinx.locale.get_translation()`. - .. versionadded:: 1.8 + .. version-added:: 1.8 """ locale.init([locale_dir], self.config.language, catalog) locale.init_console(locale_dir, catalog) @@ -1814,7 +1814,7 @@ def set_html_assets_policy(self, policy: Literal['always', 'per_page']) -> None: - always: include the assets in all the pages - per_page: include the assets only in pages where they are used - .. versionadded: 4.1 + .. version-added: 4.1 """ if policy not in {'always', 'per_page'}: raise ValueError('policy %s is not supported' % policy) diff --git a/sphinx/domains/__init__.py b/sphinx/domains/__init__.py index 17aa7bdc453..f4934080cc2 100644 --- a/sphinx/domains/__init__.py +++ b/sphinx/domains/__init__.py @@ -276,7 +276,7 @@ def resolve_any_xref( role that could have created the same reference, e.g. ``'py:func'``. ``newnode`` is what :meth:`resolve_xref` would return. - .. versionadded:: 1.3 + .. version-added:: 1.3 """ raise NotImplementedError diff --git a/sphinx/domains/_index.py b/sphinx/domains/_index.py index 3845a97ba7b..8fdef7489b9 100644 --- a/sphinx/domains/_index.py +++ b/sphinx/domains/_index.py @@ -68,7 +68,7 @@ class Index(ABC): your domain's `indices` list. Extensions can add indices to existing domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain`. - .. versionchanged:: 3.0 + .. version-changed:: 3.0 Index pages can be referred by domain name and index name via :rst:role:`ref` role. diff --git a/sphinx/domains/python/__init__.py b/sphinx/domains/python/__init__.py index a0a0571f069..1aeb653dfb3 100644 --- a/sphinx/domains/python/__init__.py +++ b/sphinx/domains/python/__init__.py @@ -797,7 +797,7 @@ def note_object( ) -> None: """Note a python object for cross reference. - .. versionadded:: 2.1 + .. version-added:: 2.1 """ if name in self.objects: other = self.objects[name] @@ -831,7 +831,7 @@ def note_module( ) -> None: """Note a python module for cross reference. - .. versionadded:: 2.1 + .. version-added:: 2.1 """ self.modules[name] = ModuleEntry( docname=self.env.current_document.docname, diff --git a/sphinx/domains/std/__init__.py b/sphinx/domains/std/__init__.py index 556cb5c5d40..f33cd1025e5 100644 --- a/sphinx/domains/std/__init__.py +++ b/sphinx/domains/std/__init__.py @@ -826,7 +826,7 @@ def note_hyperlink_target( node_id to node. Therefore, it is very fragile to calling this without understanding hyperlink target framework in both docutils and Sphinx. - .. versionadded:: 3.0 + .. version-added:: 3.0 """ if name in self.anonlabels and self.anonlabels[name] != (docname, node_id): logger.warning( @@ -849,7 +849,7 @@ def note_object( ) -> None: """Note a generic object for cross reference. - .. versionadded:: 3.0 + .. version-added:: 3.0 """ if (objtype, name) in self.objects: docname = self.objects[objtype, name][0] diff --git a/sphinx/ext/linkcode.py b/sphinx/ext/linkcode.py index fc95aeaab45..c8fb9e74501 100644 --- a/sphinx/ext/linkcode.py +++ b/sphinx/ext/linkcode.py @@ -30,7 +30,7 @@ def add_linkcode_domain(domain: str, keys: list[str], override: bool = False) -> None: """Register a new list of keys to use for a domain. - .. versionadded:: 8.2 + .. version-added:: 8.2 """ if override or domain not in _DOMAIN_KEYS: _DOMAIN_KEYS[domain] = list(keys) diff --git a/sphinx/locale/__init__.py b/sphinx/locale/__init__.py index 7d0586dace8..585ded23e00 100644 --- a/sphinx/locale/__init__.py +++ b/sphinx/locale/__init__.py @@ -150,7 +150,7 @@ def init_console( ) -> tuple[NullTranslations, bool]: """Initialize locale for console. - .. versionadded:: 1.8 + .. version-added:: 1.8 """ if locale_dir is None: locale_dir = _LOCALE_DIR @@ -201,7 +201,7 @@ def setup(app): ``${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo``. The :confval:`language` is used for the searching. - .. versionadded:: 1.8 + .. version-added:: 1.8 """ def gettext(message: str) -> str: diff --git a/sphinx/search/__init__.py b/sphinx/search/__init__.py index b835b7b36db..80e1cf9b7fd 100644 --- a/sphinx/search/__init__.py +++ b/sphinx/search/__init__.py @@ -60,7 +60,7 @@ class SearchLanguage: named as ``splitQuery``. And it should take a string and return list of strings. - .. versionadded:: 3.0 + .. version-added:: 3.0 .. attribute:: js_stemmer_code diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py index 2673a3fc77f..f94ffae7ac8 100644 --- a/sphinx/util/docutils.py +++ b/sphinx/util/docutils.py @@ -474,7 +474,7 @@ class SphinxDirective(Directive): This class provides helper methods for Sphinx directives. - .. versionadded:: 1.8 + .. version-added:: 1.8 .. note:: The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx. @@ -484,7 +484,7 @@ class SphinxDirective(Directive): def env(self) -> BuildEnvironment: """Reference to the :class:`.BuildEnvironment` object. - .. versionadded:: 1.8 + .. version-added:: 1.8 """ return self.state.document.settings.env @@ -492,28 +492,28 @@ def env(self) -> BuildEnvironment: def config(self) -> Config: """Reference to the :class:`.Config` object. - .. versionadded:: 1.8 + .. version-added:: 1.8 """ return self.env.config def get_source_info(self) -> tuple[str, int]: """Get source and line number. - .. versionadded:: 3.0 + .. version-added:: 3.0 """ return self.state_machine.get_source_and_line(self.lineno) def set_source_info(self, node: Node) -> None: """Set source and line number to the node. - .. versionadded:: 2.1 + .. version-added:: 2.1 """ node.source, node.line = self.get_source_info() def get_location(self) -> str: """Get current location info for logging. - .. versionadded:: 4.2 + .. version-added:: 4.2 """ source, line = self.get_source_info() if source and line: @@ -537,7 +537,7 @@ def parse_content_to_nodes( only be children of ``Structural`` nodes, which includes ``document``, ``section``, and ``sidebar`` nodes. - .. versionadded:: 7.4 + .. version-added:: 7.4 """ return nested_parse_to_nodes( self.state, @@ -568,7 +568,7 @@ def parse_text_to_nodes( :param offset: The offset of the content. - .. versionadded:: 7.4 + .. version-added:: 7.4 """ if offset == -1: offset = self.content_offset @@ -593,7 +593,7 @@ def parse_inline( :returns: A list of nodes (text and inline elements) and a list of system_messages. - .. versionadded:: 7.4 + .. version-added:: 7.4 """ if lineno == -1: lineno = self.lineno @@ -605,7 +605,7 @@ class SphinxRole: This class provides helper methods for Sphinx roles. - .. versionadded:: 2.0 + .. version-added:: 2.0 .. note:: The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx. @@ -662,7 +662,7 @@ def run(self) -> tuple[list[Node], list[system_message]]: def env(self) -> BuildEnvironment: """Reference to the :class:`.BuildEnvironment` object. - .. versionadded:: 2.0 + .. version-added:: 2.0 """ return self.inliner.document.settings.env @@ -670,24 +670,24 @@ def env(self) -> BuildEnvironment: def config(self) -> Config: """Reference to the :class:`.Config` object. - .. versionadded:: 2.0 + .. version-added:: 2.0 """ return self.env.config def get_source_info(self, lineno: int | None = None) -> tuple[str, int]: - # .. versionadded:: 3.0 + # .. version-added:: 3.0 if lineno is None: lineno = self.lineno return self.inliner.reporter.get_source_and_line(lineno) # type: ignore[attr-defined] def set_source_info(self, node: Node, lineno: int | None = None) -> None: - # .. versionadded:: 2.0 + # .. version-added:: 2.0 node.source, node.line = self.get_source_info(lineno) def get_location(self) -> str: """Get current location info for logging. - .. versionadded:: 4.2 + .. version-added:: 4.2 """ source, line = self.get_source_info() if source and line: @@ -706,7 +706,7 @@ class ReferenceRole(SphinxRole): the role. The parsed result; link title and target will be stored to ``self.title`` and ``self.target``. - .. versionadded:: 2.0 + .. version-added:: 2.0 """ # fmt: off @@ -756,7 +756,7 @@ class SphinxTranslator(nodes.NodeVisitor): It also provides helper methods for Sphinx translators. - .. versionadded:: 2.0 + .. version-added:: 2.0 .. note:: The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx. diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index 9ad035c49af..9e71cf23b4a 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -341,7 +341,7 @@ def prefixed_warnings(prefix: str) -> Iterator[None]: >>> with prefixed_warnings("prefix:"): >>> logger.warning('Warning message!') # => prefix: Warning message! - .. versionadded:: 2.0 + .. version-added:: 2.0 """ logger = logging.getLogger(NAMESPACE) warning_handler = None diff --git a/sphinx/util/parsing.py b/sphinx/util/parsing.py index 4c4a6477683..aa686781467 100644 --- a/sphinx/util/parsing.py +++ b/sphinx/util/parsing.py @@ -50,7 +50,7 @@ def nested_parse_to_nodes( If this is True, then title underlines must match those in the surrounding document, otherwise the behaviour is undefined. - .. versionadded:: 7.4 + .. version-added:: 7.4 """ document = state.document content = _text_to_string_list(