feat: add custom versionchanged/versionadded logic for replacing |vnext| (DisnakeDev#1376)

Signed-off-by: arielle <me@arielle.codes>
Co-authored-by: vi <8530778+shiftinv@users.noreply.github.com>

Author: onerandomusername

CONTRIBUTING.md

@@ -121,3 +121,8 @@ We use [towncrier](https://github.com/twisted/towncrier) for managing our change
 ### Documentation
 We use Sphinx to build the project's documentation, which includes [automatically generating](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) the API Reference from docstrings using the [NumPy style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html).  
 To build the documentation locally, use `pdm run docs` and visit http://127.0.0.1:8009/ once built.
+
+Changes should be marked with a [version directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions) as documented on the Sphinx documentation.
+
+For the `version` argument, provide ``|vnext|`` as the argument.
+We have a custom role which replaces ``|vnext|`` with the next version of the library upon building the documentation.

docs/conf.py

@@ -56,6 +56,7 @@
     "collapse",
     "enumattrs",
     "nitpick_file_ignorer",
+    "versionchange",
 ]
 
 autodoc_member_order = "bysource"

docs/extensions/versionchange.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sphinx.domains.changeset
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+    from ._types import SphinxExtensionMeta
+
+
+class VersionAddedNext(sphinx.domains.changeset.VersionChange):
+    """Add support for a `|vnext|` version placeholder in versionadded directives."""
+
+    def run(self):
+        # If the argument is |vnext|, replace with config version
+        if self.arguments and self.arguments[0] == "|vnext|":
+            # Get the version from the Sphinx config
+            version = self.env.config.version
+            self.arguments[0] = version
+        return super().run()
+
+
+def setup(app: Sphinx) -> SphinxExtensionMeta:
+    app.add_directive("versionadded", VersionAddedNext, override=True)
+    app.add_directive("versionchanged", VersionAddedNext, override=True)
+    app.add_directive("deprecated", VersionAddedNext, override=True)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }