Add a `versionremoved` directive (#11905)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

doc/usage/builders/index.rst

@@ -453,9 +453,9 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
 .. class:: ChangesBuilder
 
    This builder produces an HTML overview of all :rst:dir:`versionadded`,
-   :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the
-   current :confval:`version`.  This is useful to generate a ChangeLog file, for
-   example.
+   :rst:dir:`versionchanged`, :rst:dir:`deprecated` and :rst:dir:`versionremoved`
+   directives for the current :confval:`version`.  This is useful to generate a
+   changelog file, for example.
 
    .. autoattribute:: name
 

doc/usage/restructuredtext/directives.rst

@@ -323,6 +323,18 @@ units as well as normal text.
       .. deprecated:: 3.1
          Use :func:`spam` instead.
 
+.. rst:directive:: .. versionremoved:: version
+
+   Similar to :rst:dir:`versionadded`, but describes when the feature was removed.
+   An explanation may be provided to inform the reader what to use instead,
+   or why the feature was removed.
+   Example::
+
+      .. versionremoved:: 4.0
+         The :func:`spam` function is more flexible, and should be used instead.
+
+   .. versionadded:: 7.3
+
 .. rst:directive:: seealso
 
    Many sections include a list of references to module documentation or

sphinx/addnodes.py

@@ -406,8 +406,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" and "deprecated"
-    directives.
+    Currently used for "versionadded", "versionchanged", "deprecated"
+    and "versionremoved" directives.
     """
 
 

sphinx/builders/changes.py

@@ -24,7 +24,7 @@ logger = logging.getLogger(__name__)
 
 class ChangesBuilder(Builder):
     """
-    Write a summary with all versionadded/changed directives.
+    Write a summary with all versionadded/changed/deprecated/removed directives.
     """
 
     name = 'changes'
@@ -43,6 +43,7 @@ class ChangesBuilder(Builder):
         'versionadded': 'added',
         'versionchanged': 'changed',
         'deprecated': 'deprecated',
+        'versionremoved': 'removed',
     }
 
     def write(self, *ignored: Any) -> None:
@@ -106,7 +107,9 @@ class ChangesBuilder(Builder):
 
         hltext = ['.. versionadded:: %s' % version,
                   '.. versionchanged:: %s' % version,
-                  '.. deprecated:: %s' % version]
+                  '.. deprecated:: %s' % version,
+                  '.. versionremoved:: %s' % version,
+                  ]
 
         def hl(no: int, line: str) -> str:
             line = '<a name="L%s"> </a>' % no + html.escape(line)
@@ -143,7 +146,7 @@ class ChangesBuilder(Builder):
 
     def hl(self, text: str, version: str) -> str:
         text = html.escape(text)
-        for directive in ('versionchanged', 'versionadded', 'deprecated'):
+        for directive in ('versionchanged', 'versionadded', 'deprecated', 'versionremoved'):
             text = text.replace(f'.. {directive}:: {version}',
                                 f'<b>.. {directive}:: {version}</b>')
         return text

sphinx/domains/changeset.py

@@ -23,12 +23,14 @@ versionlabels = {
     'versionadded':   _('New in version %s'),
     'versionchanged': _('Changed in version %s'),
     'deprecated':     _('Deprecated since version %s'),
+    'versionremoved': _('Removed in version %s'),
 }
 
 versionlabel_classes = {
     'versionadded':     'added',
     'versionchanged':   'changed',
     'deprecated':       'deprecated',
+    'versionremoved':   'removed',
 }
 
 
@@ -153,6 +155,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_directive('deprecated', VersionChange)
     app.add_directive('versionadded', VersionChange)
     app.add_directive('versionchanged', VersionChange)
+    app.add_directive('versionremoved', VersionChange)
 
     return {
         'version': 'builtin',

tests/roots/test-changes/base.rst

@@ -10,6 +10,9 @@ Version markup
 .. deprecated:: 0.6
    Boring stuff.
 
+.. versionremoved:: 0.6
+   Goodbye boring stuff.
+
 .. versionadded:: 1.2
 
    First paragraph of versionadded.

tests/roots/test-intl/versionchange.txt

@@ -14,3 +14,5 @@ i18n with versionchange
 .. versionchanged:: 1.0
 
    This is the *first* paragraph of versionchanged.
+
+.. versionremoved:: 1.0 This is the *first* paragraph of versionremoved.

tests/roots/test-intl/xx/LC_MESSAGES/versionchange.po

@@ -31,3 +31,5 @@ msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSIONADDED."
 msgid "This is the *first* paragraph of versionchanged."
 msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSIONCHANGED."
 
+msgid "This is the *first* paragraph of versionremoved."
+msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSIONREMOVED."

tests/roots/test-root/markup.txt

@@ -274,6 +274,9 @@ Version markup
 .. deprecated:: 0.6
    Boring stuff.
 
+.. versionremoved:: 0.6
+   Goodbye boring stuff.
+
 .. versionadded:: 1.2
 
    First paragraph of versionadded.

tests/test_builders/test_build_html_5_output.py

@@ -120,6 +120,7 @@ def tail_check(check):
      tail_check('First paragraph of versionchanged')),
     ('markup.html', ".//div[@class='versionchanged']/p",
      'Second paragraph of versionchanged'),
+    ('markup.html', ".//div[@class='versionremoved']/p/span", 'Removed in version 0.6: '),
     # footnote reference
     ('markup.html', ".//a[@class='footnote-reference brackets']", r'1'),
     # created by reference lookup

tests/test_intl/test_intl.py

@@ -840,6 +840,12 @@ def test_html_versionchanges(app):
     matched_content = get_content(result, "versionchanged")
     assert expect3 == matched_content
 
+    expect4 = (
+        """<p><span class="versionmodified removed">Removed in version 1.0: </span>"""
+        """THIS IS THE <em>FIRST</em> PARAGRAPH OF VERSIONREMOVED.</p>\n""")
+    matched_content = get_content(result, "versionremoved")
+    assert expect4 == matched_content
+
 
 @sphinx_intl
 @pytest.mark.sphinx('html')