Add versionremoved directive to complement versionadded and deprecated

[consideRatio]

Background

In PEP4, deprecated is a word used to indicate something may be removed in the future.

Usage of a module may be ‘deprecated’, which means that it may be removed from a future Python release.

The existing sphinx directives versionadded, versionchanged, and deprecated are excellent in reference documentation, but when something deprecated is removed, its not clear what to do without a versionremoved directive. Authoring reference documentation, I'd like to document that something has been around even after it is removed and can't be used any more.

Proposal

I suggest a versionremoved directive is added alongside the other related directives below, together with new documentation alongside versionadded as seen here.

sphinx/sphinx/domains/changeset.py

Lines 21 to 31 in d3c91f9

	versionlabels = {
	'versionadded': _('New in version %s'),
	'versionchanged': _('Changed in version %s'),
	'deprecated': _('Deprecated since version %s'),
	}
	versionlabel_classes = {
	'versionadded': 'added',
	'versionchanged': 'changed',
	'deprecated': 'deprecated',
	}

Looking into the details, it seems like this is relevant to update:

• Update versionlabels and versionlabel_classes in domains/changeset.py
• Update docstring in addnotes.py
• Update logic in builders/changes.py
• Update tests in by searching for paragraph of versionchanged without case sensitivity in the code base

Options

Sphinx users can patch sphinx via the sphinx extension sphinx-removed-in does, from where the proposal stems from - thank you @atodorov, @hroncok, @nicoddemus who have made commits to that project.

For sphinx>=2, this extension is like adding this to a conf.py file:

# -- Add versionremoved directive ---------------------------------------------------
# ref: https://github.com/sphinx-doc/sphinx/issues/11480
#
from sphinx.domains.changeset import VersionChange, versionlabel_classes, versionlabels


def setup(app):
    if "versionremoved" not in versionlabels:
        versionlabels["versionremoved"] = "Removed in version %s"
        versionlabel_classes["versionremoved"] = "removed"
        app.add_directive("versionremoved", VersionChange)

[picnixz]

PR is welcomed!

[hugovk]

Please see PR #11905.

[consideRatio]

Thank you @hugovk and everyone involved!! 🎉 ❤️