Skip to content

Commit ff4146d

Browse files
stephenfinstephenfin
committed
Add versiondeprecated admonition
For consistency with other version* admonitions. 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 this 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). Signed-off-by: Stephen Finucane <stephen@that.guru>
1 parent 7b4164a commit ff4146d

File tree

15 files changed

+68
-34
lines changed

15 files changed

+68
-34
lines changed

‎doc/development/html_themes/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ If your theme package contains two or more themes, please call
214214
.. versionadded:: 1.2
215215
'sphinx_themes' entry_points feature.
216216

217-
.. deprecated:: 1.6
217+
.. versionchanged:: 1.6
218218
``sphinx_themes`` entry_points has been deprecated.
219219

220220
.. versionadded:: 1.6

‎doc/development/html_themes/templating.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -188,24 +188,24 @@ is deprecated in favor of separate sidebar templates, which can be included via
188188
``sidebartoc``
189189
The table of contents within the sidebar.
190190

191-
.. deprecated:: 1.0
191+
.. versiondeprecated:: 1.0
192192

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

196-
.. deprecated:: 1.0
196+
.. versiondeprecated:: 1.0
197197

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

202-
.. deprecated:: 1.0
202+
.. versiondeprecated:: 1.0
203203

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

208-
.. deprecated:: 1.0
208+
.. versiondeprecated:: 1.0
209209

210210

211211
Configuration Variables
@@ -237,7 +237,7 @@ Overriding works like this::
237237

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

240-
.. deprecated:: 1.8.0
240+
.. versiondeprecated:: 1.8.0
241241

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

‎doc/extdev/markupapi.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ and does not contain any structural elements
203203
with switch_source_input(self.state, self.result):
204204
parsed = nested_parse_to_nodes(self.state, self.result)
205205
206-
.. deprecated:: 1.7
206+
.. versiondeprecated:: 1.7
207207

208208
Until Sphinx 1.6, ``sphinx.ext.autodoc.AutodocReporter`` was used for this
209209
purpose. It is replaced by ``switch_source_input()``.

‎doc/latex.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,8 @@ Keys that you may want to override include:
288288

289289
Default: ``''``
290290

291-
.. deprecated:: 1.5
291+
.. versiondeprecated:: 1.5
292+
292293
Use ``'atendofbody'`` key instead.
293294

294295
Keys that don't need to be overridden unless in special cases are:

‎doc/usage/configuration.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1157,7 +1157,7 @@ Options for source files
11571157
The recommended encoding is ``'utf-8-sig'``.
11581158

11591159
.. versionadded:: 0.5
1160-
.. deprecated:: 8.3
1160+
.. versiondeprecated:: 8.3
11611161
Support for source encodings other than UTF-8 is deprecated.
11621162
Sphinx 10 will only support UTF-8 files.
11631163

@@ -1586,7 +1586,7 @@ and also make use of these options.
15861586
.. versionadded:: 3.2
15871587
.. versionchanged:: 4.0
15881588
It defaults to :code-py:`'inline'`.
1589-
.. deprecated:: 4.0
1589+
.. versiondeprecated:: 4.0
15901590

15911591
.. confval:: html_context
15921592
:type: :code-py:`dict[str, Any]`
@@ -1853,7 +1853,7 @@ and also make use of these options.
18531853
.. versionadded:: 1.0
18541854
The ability to use globbing keys and to specify multiple sidebars.
18551855

1856-
.. deprecated:: 1.7
1856+
.. versiondeprecated:: 1.7
18571857
A single string value for :confval:`!html_sidebars` will be removed.
18581858

18591859
.. versionchanged:: 2.0
@@ -2103,7 +2103,8 @@ and also make use of these options.
21032103
`Janome <https://pypi.org/project/Janome/>`_ is required.
21042104

21052105

2106-
.. deprecated:: 1.6
2106+
.. versiondeprecated:: 1.6
2107+
21072108
``'mecab'``, ``'janome'`` and ``'default'`` is deprecated.
21082109
To keep compatibility,
21092110
``'mecab'``, ``'janome'`` and ``'default'`` are also acceptable.

‎doc/usage/restructuredtext/directives.rst

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -572,19 +572,21 @@ Describing changes between versions
572572
.. versionchanged:: 2.8
573573
The *spam* parameter is now of type *boson*.
574574

575-
.. rst:directive:: .. deprecated:: version [brief explanation]
575+
.. rst:directive:: .. versiondeprecated:: version [brief explanation]
576576
577577
Similar to :rst:dir:`versionadded`, but describes when the feature was
578578
deprecated.
579579
A *brief* explanation can also be given,
580580
for example to tell the reader what to use instead.
581581

582+
.. versionadded:: 8.3
583+
582584
Example::
583585

584-
.. deprecated:: 3.1
586+
.. versiondeprecated:: 3.1
585587
Use :py:func:`spam` instead.
586588

587-
.. deprecated:: 3.1
589+
.. versiondeprecated:: 3.1
588590
Use :py:func:`!spam` instead.
589591

590592
.. rst:directive:: .. versionremoved:: version [brief explanation]
@@ -603,6 +605,12 @@ Describing changes between versions
603605
.. versionremoved:: 4.0
604606
The :py:func:`!spam` function is more flexible, and should be used instead.
605607

608+
.. rst:directive:: .. deprecated:: version [brief explanation]
609+
610+
A legacy alias for :rst:dir:`versiondeprecated`.
611+
612+
.. versiondeprecated:: 8.3
613+
606614

607615
Presentational
608616
^^^^^^^^^^^^^^

‎sphinx/application.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1117,7 +1117,7 @@ def setup(app):
11171117
11181118
.. versionchanged:: 0.6
11191119
Docutils 0.5-style directive classes are now supported.
1120-
.. deprecated:: 1.8
1120+
.. versionchanged:: 1.8
11211121
Docutils 0.4-style (function based) directives support is deprecated.
11221122
.. versionchanged:: 1.8
11231123
Add *override* keyword.

‎sphinx/builders/changes.py

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,9 @@ def get_outdated_docs(self) -> str:
4545
typemap = {
4646
'versionadded': 'added',
4747
'versionchanged': 'changed',
48-
'deprecated': 'deprecated',
48+
'versiondeprecated': 'deprecated',
4949
'versionremoved': 'removed',
50+
'deprecated': 'deprecated',
5051
}
5152

5253
def write_documents(self, _docnames: Set[str]) -> None:
@@ -114,8 +115,9 @@ def write_documents(self, _docnames: Set[str]) -> None:
114115
hltext = [
115116
f'.. versionadded:: {version}',
116117
f'.. versionchanged:: {version}',
117-
f'.. deprecated:: {version}',
118+
f'.. versiondeprecated:: {version}',
118119
f'.. versionremoved:: {version}',
120+
f'.. deprecated:: {version}',
119121
]
120122

121123
def hl(no: int, line: str) -> str:

‎sphinx/domains/changeset.py

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,17 @@
2525
versionlabels = {
2626
'versionadded': _('Added in version %s'),
2727
'versionchanged': _('Changed in version %s'),
28-
'deprecated': _('Deprecated since version %s'),
28+
'versiondeprecated': _('Deprecated since version %s'),
2929
'versionremoved': _('Removed in version %s'),
30+
'deprecated': _('Deprecated since version %s'),
3031
}
3132

3233
versionlabel_classes = {
3334
'versionadded': 'added',
3435
'versionchanged': 'changed',
35-
'deprecated': 'deprecated',
36+
'versiondeprecated': 'deprecated',
3637
'versionremoved': 'removed',
38+
'deprecated': 'deprecated',
3739
}
3840

3941

@@ -171,6 +173,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
171173
app.add_directive('deprecated', VersionChange)
172174
app.add_directive('versionadded', VersionChange)
173175
app.add_directive('versionchanged', VersionChange)
176+
app.add_directive('versiondeprecated', VersionChange)
174177
app.add_directive('versionremoved', VersionChange)
175178

176179
return {

‎tests/roots/test-changes/base.rst

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Version markup
77
.. versionchanged:: 0.6
88
Even more funny stuff.
99

10-
.. deprecated:: 0.6
10+
.. versiondeprecated:: 0.6
1111
Boring stuff.
1212

1313
.. versionremoved:: 0.6
@@ -21,3 +21,6 @@ Version markup
2121
First paragraph of versionchanged.
2222

2323
Second paragraph of versionchanged.
24+
25+
.. deprecated:: 1.3
26+
First paragraph of deprecated.

0 commit comments

Comments
 (0)