Debian Codegraph @

docs/tox_conf.py

raw
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