Skip to content

Commit cbfd392

Browse files
AA-TurnerAA-Turner
authored
GH-121970: Extract availability into a new extension (#125082)
1 parent f2cb399 commit cbfd392

File tree

3 files changed

+126
-76
lines changed

3 files changed

+126
-76
lines changed

‎Doc/conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121

2222
extensions = [
2323
'audit_events',
24+
'availability',
2425
'c_annotations',
2526
'glossary_search',
2627
'lexers',

‎Doc/tools/extensions/availability.py

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
"""Support for documenting platform availability"""
2+
3+
from __future__ import annotations
4+
5+
from typing import TYPE_CHECKING
6+
7+
from docutils import nodes
8+
from sphinx import addnodes
9+
from sphinx.util import logging
10+
from sphinx.util.docutils import SphinxDirective
11+
12+
if TYPE_CHECKING:
13+
from sphinx.application import Sphinx
14+
from sphinx.util.typing import ExtensionMetadata
15+
16+
logger = logging.getLogger("availability")
17+
18+
# known platform, libc, and threading implementations
19+
_PLATFORMS = frozenset({
20+
"AIX",
21+
"Android",
22+
"BSD",
23+
"DragonFlyBSD",
24+
"Emscripten",
25+
"FreeBSD",
26+
"GNU/kFreeBSD",
27+
"iOS",
28+
"Linux",
29+
"macOS",
30+
"NetBSD",
31+
"OpenBSD",
32+
"POSIX",
33+
"Solaris",
34+
"Unix",
35+
"VxWorks",
36+
"WASI",
37+
"Windows",
38+
})
39+
_LIBC = frozenset({
40+
"BSD libc",
41+
"glibc",
42+
"musl",
43+
})
44+
_THREADING = frozenset({
45+
# POSIX platforms with pthreads
46+
"pthreads",
47+
})
48+
KNOWN_PLATFORMS = _PLATFORMS | _LIBC | _THREADING
49+
50+
51+
class Availability(SphinxDirective):
52+
has_content = True
53+
required_arguments = 1
54+
optional_arguments = 0
55+
final_argument_whitespace = True
56+
57+
def run(self) -> list[nodes.container]:
58+
title = "Availability"
59+
refnode = addnodes.pending_xref(
60+
title,
61+
nodes.inline(title, title, classes=["xref", "std", "std-ref"]),
62+
refdoc=self.env.docname,
63+
refdomain="std",
64+
refexplicit=True,
65+
reftarget="availability",
66+
reftype="ref",
67+
refwarn=True,
68+
)
69+
sep = nodes.Text(": ")
70+
parsed, msgs = self.state.inline_text(self.arguments[0], self.lineno)
71+
pnode = nodes.paragraph(title, "", refnode, sep, *parsed, *msgs)
72+
self.set_source_info(pnode)
73+
cnode = nodes.container("", pnode, classes=["availability"])
74+
self.set_source_info(cnode)
75+
if self.content:
76+
self.state.nested_parse(self.content, self.content_offset, cnode)
77+
self.parse_platforms()
78+
79+
return [cnode]
80+
81+
def parse_platforms(self) -> dict[str, str | bool]:
82+
"""Parse platform information from arguments
83+
84+
Arguments is a comma-separated string of platforms. A platform may
85+
be prefixed with "not " to indicate that a feature is not available.
86+
87+
Example::
88+
89+
.. availability:: Windows, Linux >= 4.2, not WASI
90+
91+
Arguments like "Linux >= 3.17 with glibc >= 2.27" are currently not
92+
parsed into separate tokens.
93+
"""
94+
platforms = {}
95+
for arg in self.arguments[0].rstrip(".").split(","):
96+
arg = arg.strip()
97+
platform, _, version = arg.partition(" >= ")
98+
if platform.startswith("not "):
99+
version = False
100+
platform = platform.removeprefix("not ")
101+
elif not version:
102+
version = True
103+
platforms[platform] = version
104+
105+
if unknown := set(platforms).difference(KNOWN_PLATFORMS):
106+
logger.warning(
107+
"Unknown platform%s or syntax '%s' in '.. availability:: %s', "
108+
"see %s:KNOWN_PLATFORMS for a set of known platforms.",
109+
"s" if len(platforms) != 1 else "",
110+
" ".join(sorted(unknown)),
111+
self.arguments[0],
112+
__file__,
113+
)
114+
115+
return platforms
116+
117+
118+
def setup(app: Sphinx) -> ExtensionMetadata:
119+
app.add_directive("availability", Availability)
120+
121+
return {
122+
"version": "1.0",
123+
"parallel_read_safe": True,
124+
"parallel_write_safe": True,
125+
}

‎Doc/tools/extensions/pyspecific.py

-76
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@
2424
from sphinx.domains.changeset import VersionChange, versionlabels, versionlabel_classes
2525
from sphinx.domains.python import PyFunction, PyMethod, PyModule
2626
from sphinx.locale import _ as sphinx_gettext
27-
from sphinx.util import logging
2827
from sphinx.util.docutils import SphinxDirective
2928
from sphinx.writers.text import TextWriter, TextTranslator
3029
from sphinx.util.display import status_iterator
@@ -108,80 +107,6 @@ def run(self):
108107
return [pnode]
109108

110109

111-
# Support for documenting platform availability
112-
113-
class Availability(SphinxDirective):
114-
115-
has_content = True
116-
required_arguments = 1
117-
optional_arguments = 0
118-
final_argument_whitespace = True
119-
120-
# known platform, libc, and threading implementations
121-
known_platforms = frozenset({
122-
"AIX", "Android", "BSD", "DragonFlyBSD", "Emscripten", "FreeBSD",
123-
"GNU/kFreeBSD", "Linux", "NetBSD", "OpenBSD", "POSIX", "Solaris",
124-
"Unix", "VxWorks", "WASI", "Windows", "macOS", "iOS",
125-
# libc
126-
"BSD libc", "glibc", "musl",
127-
# POSIX platforms with pthreads
128-
"pthreads",
129-
})
130-
131-
def run(self):
132-
availability_ref = ':ref:`Availability <availability>`: '
133-
avail_nodes, avail_msgs = self.state.inline_text(
134-
availability_ref + self.arguments[0],
135-
self.lineno)
136-
pnode = nodes.paragraph(availability_ref + self.arguments[0],
137-
'', *avail_nodes, *avail_msgs)
138-
self.set_source_info(pnode)
139-
cnode = nodes.container("", pnode, classes=["availability"])
140-
self.set_source_info(cnode)
141-
if self.content:
142-
self.state.nested_parse(self.content, self.content_offset, cnode)
143-
self.parse_platforms()
144-
145-
return [cnode]
146-
147-
def parse_platforms(self):
148-
"""Parse platform information from arguments
149-
150-
Arguments is a comma-separated string of platforms. A platform may
151-
be prefixed with "not " to indicate that a feature is not available.
152-
153-
Example::
154-
155-
.. availability:: Windows, Linux >= 4.2, not WASI
156-
157-
Arguments like "Linux >= 3.17 with glibc >= 2.27" are currently not
158-
parsed into separate tokens.
159-
"""
160-
platforms = {}
161-
for arg in self.arguments[0].rstrip(".").split(","):
162-
arg = arg.strip()
163-
platform, _, version = arg.partition(" >= ")
164-
if platform.startswith("not "):
165-
version = False
166-
platform = platform[4:]
167-
elif not version:
168-
version = True
169-
platforms[platform] = version
170-
171-
unknown = set(platforms).difference(self.known_platforms)
172-
if unknown:
173-
cls = type(self)
174-
logger = logging.getLogger(cls.__qualname__)
175-
logger.warning(
176-
f"Unknown platform(s) or syntax '{' '.join(sorted(unknown))}' "
177-
f"in '.. availability:: {self.arguments[0]}', see "
178-
f"{__file__}:{cls.__qualname__}.known_platforms for a set "
179-
"known platforms."
180-
)
181-
182-
return platforms
183-
184-
185110
# Support for documenting decorators
186111

187112
class PyDecoratorMixin(object):
@@ -492,7 +417,6 @@ def setup(app):
492417
app.add_role('issue', issue_role)
493418
app.add_role('gh', gh_issue_role)
494419
app.add_directive('impl-detail', ImplementationDetail)
495-
app.add_directive('availability', Availability)
496420
app.add_directive('versionadded', PyVersionChange, override=True)
497421
app.add_directive('versionchanged', PyVersionChange, override=True)
498422
app.add_directive('versionremoved', PyVersionChange, override=True)

0 commit comments

Comments
 (0)