| 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 |
} |