Debian Codegraph @

Doc/tools/extensions/availability.py

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