Debian Codegraph @

Doc/tools/extensions/changes.py

raw
1 """Support for documenting version of changes, additions, deprecations."""
2
3 from __future__ import annotations
4
5 import re
6
7 from docutils import nodes
8 from sphinx import addnodes
9 from sphinx.domains.changeset import (
10 VersionChange,
11 versionlabel_classes,
12 versionlabels,
13 )
14 from sphinx.locale import _ as sphinx_gettext
15
16 TYPE_CHECKING = False
17 if TYPE_CHECKING:
18 from docutils.nodes import Node
19 from sphinx.application import Sphinx
20 from sphinx.util.typing import ExtensionMetadata
21
22
23 def expand_version_arg(argument: str, release: str) -> str:
24 """Expand "next" to the current version"""
25 if argument == "next":
26 return sphinx_gettext("{} (unreleased)").format(release)
27 return argument
28
29
30 class PyVersionChange(VersionChange):
31 def run(self) -> list[Node]:
32 # Replace the 'next' special token with the current development version
33 self.arguments[0] = expand_version_arg(
34 self.arguments[0], self.config.release
35 )
36 return super().run()
37
38
39 class DeprecatedRemoved(VersionChange):
40 required_arguments = 2
41
42 _deprecated_label = sphinx_gettext(
43 "Deprecated since version %s, will be removed in version %s"
44 )
45 _removed_label = sphinx_gettext(
46 "Deprecated since version %s, removed in version %s"
47 )
48
49 def run(self) -> list[Node]:
50 # Replace the first two arguments (deprecated version and removed version)
51 # with a single tuple of both versions.
52 version_deprecated = expand_version_arg(
53 self.arguments[0], self.config.release
54 )
55 version_removed = self.arguments.pop(1)
56 if version_removed == "next":
57 raise ValueError(
58 "deprecated-removed:: second argument cannot be `next`"
59 )
60 self.arguments[0] = version_deprecated, version_removed
61
62 # Set the label based on if we have reached the removal version
63 current_version = tuple(map(int, self.config.version.split(".")))
64 removed_version = tuple(map(int, version_removed.split(".")))
65 if current_version < removed_version:
66 versionlabels[self.name] = self._deprecated_label
67 versionlabel_classes[self.name] = "deprecated"
68 else:
69 versionlabels[self.name] = self._removed_label
70 versionlabel_classes[self.name] = "removed"
71 try:
72 return super().run()
73 finally:
74 # reset versionlabels and versionlabel_classes
75 versionlabels[self.name] = ""
76 versionlabel_classes[self.name] = ""
77
78
79 class SoftDeprecated(PyVersionChange):
80 """Directive for soft deprecations that auto-links to the glossary term.
81
82 Usage::
83
84 .. soft-deprecated:: 3.15
85
86 Use :func:`new_thing` instead.
87
88 Renders as: "Soft deprecated since version 3.15: Use new_thing() instead."
89 with "Soft deprecated" linking to the glossary definition.
90 """
91
92 _TERM_RE = re.compile(r":term:`([^`]+)`")
93
94 def run(self) -> list[Node]:
95 versionlabels[self.name] = sphinx_gettext(
96 ":term:`Soft deprecated` since version %s"
97 )
98 versionlabel_classes[self.name] = "soft-deprecated"
99 try:
100 result = super().run()
101 finally:
102 versionlabels[self.name] = ""
103 versionlabel_classes[self.name] = ""
104
105 for node in result:
106 # Add "versionchanged" class so existing theme CSS applies
107 node["classes"] = node.get("classes", []) + ["versionchanged"]
108 # Replace the plain-text "Soft deprecated" with a glossary reference
109 for inline in node.findall(nodes.inline):
110 if "versionmodified" in inline.get("classes", []):
111 self._add_glossary_link(inline)
112
113 return result
114
115 @classmethod
116 def _add_glossary_link(cls, inline: nodes.inline) -> None:
117 """Replace :term:`soft deprecated` text with a cross-reference to the
118 'Soft deprecated' glossary entry."""
119 for child in inline.children:
120 if not isinstance(child, nodes.Text):
121 continue
122
123 text = str(child)
124 match = cls._TERM_RE.search(text)
125 if match is None:
126 continue
127
128 ref = addnodes.pending_xref(
129 "",
130 nodes.Text(match.group(1)),
131 refdomain="std",
132 reftype="term",
133 reftarget="soft deprecated",
134 refwarn=True,
135 )
136
137 start, end = match.span()
138 new_nodes: list[nodes.Node] = []
139 if start > 0:
140 new_nodes.append(nodes.Text(text[:start]))
141 new_nodes.append(ref)
142 if end < len(text):
143 new_nodes.append(nodes.Text(text[end:]))
144
145 child.parent.replace(child, new_nodes)
146 break
147
148
149 def setup(app: Sphinx) -> ExtensionMetadata:
150 # Override Sphinx's directives with support for 'next'
151 app.add_directive("versionadded", PyVersionChange, override=True)
152 app.add_directive("versionchanged", PyVersionChange, override=True)
153 app.add_directive("versionremoved", PyVersionChange, override=True)
154 app.add_directive("deprecated", PyVersionChange, override=True)
155
156 # Register the ``.. deprecated-removed::`` directive
157 app.add_directive("deprecated-removed", DeprecatedRemoved)
158
159 # Register the ``.. soft-deprecated::`` directive
160 app.add_directive("soft-deprecated", SoftDeprecated)
161
162 return {
163 "version": "1.0",
164 "parallel_read_safe": True,
165 "parallel_write_safe": True,
166 }