| 1 |
from __future__ import annotations |
| 2 |
|
| 3 |
from typing import TYPE_CHECKING, Any, ClassVar, cast |
| 4 |
|
| 5 |
from docutils.nodes import Element, Node, Text, container, fully_normalize_name, literal, paragraph, reference, strong |
| 6 |
from docutils.parsers.rst.directives import flag, unchanged, unchanged_required |
| 7 |
from docutils.statemachine import StringList, string2lines |
| 8 |
from sphinx.locale import __ |
| 9 |
from sphinx.util.docutils import SphinxDirective |
| 10 |
from sphinx.util.logging import getLogger |
| 11 |
|
| 12 |
if TYPE_CHECKING: |
| 13 |
from collections.abc import Callable |
| 14 |
|
| 15 |
from docutils.parsers.rst.states import RSTState, RSTStateMachine |
| 16 |
from sphinx.domains.std import StandardDomain |
| 17 |
|
| 18 |
LOGGER = getLogger(__name__) |
| 19 |
|
| 20 |
|
| 21 |
class ToxConfig(SphinxDirective): |
| 22 |
name = "conf" |
| 23 |
has_content = True |
| 24 |
option_spec: ClassVar[dict[str, Callable[[str], Any]]] = { |
| 25 |
"keys": unchanged_required, |
| 26 |
"version_added": unchanged, |
| 27 |
"version_deprecated": unchanged, |
| 28 |
"default": unchanged, |
| 29 |
"constant": flag, |
| 30 |
"ref_suffix": unchanged, |
| 31 |
} |
| 32 |
|
| 33 |
def __init__( # noqa: PLR0913 |
| 34 |
self, |
| 35 |
name: str, |
| 36 |
arguments: list[str], |
| 37 |
options: dict[str, str], |
| 38 |
content: StringList, |
| 39 |
lineno: int, |
| 40 |
content_offset: int, |
| 41 |
block_text: str, |
| 42 |
state: RSTState, |
| 43 |
state_machine: RSTStateMachine, |
| 44 |
) -> None: |
| 45 |
super().__init__( |
| 46 |
name, |
| 47 |
arguments, |
| 48 |
options, |
| 49 |
content, |
| 50 |
lineno, |
| 51 |
content_offset, |
| 52 |
block_text, |
| 53 |
state, |
| 54 |
state_machine, |
| 55 |
) |
| 56 |
self._std_domain: StandardDomain = cast("StandardDomain", self.env.get_domain("std")) |
| 57 |
|
| 58 |
def run(self) -> list[Node]: |
| 59 |
self.env.note_reread() # this document needs to be always updated |
| 60 |
|
| 61 |
line = paragraph() |
| 62 |
line += Text("■" if "constant" in self.options else "⚙️") |
| 63 |
for key in (i.strip() for i in self.options["keys"].split(",")): |
| 64 |
line += Text(" ") |
| 65 |
self._mk_key(line, key) |
| 66 |
if "default" in self.options: |
| 67 |
default = self.options["default"] |
| 68 |
line += Text(" with default value of ") |
| 69 |
line += literal(default, default) |
| 70 |
if "version_added" in self.options: |
| 71 |
line += Text(" 📢 added in ") |
| 72 |
ver = self.options["version_added"] |
| 73 |
line += literal(ver, ver) |
| 74 |
if "version_deprecated" in self.options: |
| 75 |
line += Text(" ⚠️ deprecated in ") |
| 76 |
ver = self.options["version_deprecated"] |
| 77 |
line += literal(ver, ver) |
| 78 |
|
| 79 |
p = container("") |
| 80 |
self.state.nested_parse(StringList(string2lines("\n".join(f" {i}" for i in self.content))), 0, p) |
| 81 |
line += p |
| 82 |
|
| 83 |
return [line] |
| 84 |
|
| 85 |
def _mk_key(self, line: paragraph, key: str) -> None: |
| 86 |
ref_id = key if "ref_suffix" not in self.options else f"{key}-{self.options['ref_suffix']}" |
| 87 |
ref = reference("", refid=ref_id, reftitle=key) |
| 88 |
line.attributes["ids"].append(ref_id) |
| 89 |
st = strong() |
| 90 |
st += literal(text=key) |
| 91 |
ref += st |
| 92 |
self._register_ref(ref_id, ref_id, ref) |
| 93 |
line += ref |
| 94 |
|
| 95 |
def _register_ref(self, ref_name: str, ref_title: str, node: Element) -> None: |
| 96 |
of_name, doc_name = fully_normalize_name(ref_name), self.env.docname |
| 97 |
if of_name in self._std_domain.labels: |
| 98 |
LOGGER.warning( |
| 99 |
__("duplicate label %s, other instance in %s"), |
| 100 |
of_name, |
| 101 |
self.env.doc2path(self._std_domain.labels[of_name][0]), |
| 102 |
location=node, |
| 103 |
type="sphinx-argparse-cli", |
| 104 |
subtype=self.env.docname, |
| 105 |
) |
| 106 |
self._std_domain.anonlabels[of_name] = doc_name, ref_name |
| 107 |
self._std_domain.labels[of_name] = doc_name, ref_name, ref_title |