Debian Codegraph @

Doc/tools/extensions/pydoc_topics.py

raw
1 """Support for building "topic help" for pydoc."""
2
3 from __future__ import annotations
4
5 from time import asctime
6 from typing import TYPE_CHECKING
7
8 from sphinx.builders.text import TextBuilder
9 from sphinx.util import logging
10 from sphinx.util.display import status_iterator
11 from sphinx.util.docutils import new_document
12 from sphinx.writers.text import TextTranslator
13
14 if TYPE_CHECKING:
15 from collections.abc import Sequence, Set
16
17 from sphinx.application import Sphinx
18 from sphinx.util.typing import ExtensionMetadata
19
20 logger = logging.getLogger(__name__)
21
22 _PYDOC_TOPIC_LABELS: Sequence[str] = sorted({
23 "assert",
24 "assignment",
25 "assignment-expressions",
26 "async",
27 "atom-identifiers",
28 "atom-literals",
29 "attribute-access",
30 "attribute-references",
31 "augassign",
32 "await",
33 "binary",
34 "bitwise",
35 "bltin-code-objects",
36 "bltin-ellipsis-object",
37 "bltin-null-object",
38 "bltin-type-objects",
39 "booleans",
40 "break",
41 "callable-types",
42 "calls",
43 "class",
44 "comparisons",
45 "compound",
46 "context-managers",
47 "continue",
48 "conversions",
49 "customization",
50 "debugger",
51 "del",
52 "dict",
53 "dynamic-features",
54 "else",
55 "exceptions",
56 "execmodel",
57 "exprlists",
58 "floating",
59 "for",
60 "formatstrings",
61 "function",
62 "global",
63 "id-classes",
64 "identifiers",
65 "if",
66 "imaginary",
67 "import",
68 "in",
69 "integers",
70 "lambda",
71 "lists",
72 "naming",
73 "nonlocal",
74 "numbers",
75 "numeric-types",
76 "objects",
77 "operator-summary",
78 "pass",
79 "power",
80 "raise",
81 "return",
82 "sequence-types",
83 "shifting",
84 "slicings",
85 "specialattrs",
86 "specialnames",
87 "string-methods",
88 "strings",
89 "subscriptions",
90 "truth",
91 "try",
92 "types",
93 "typesfunctions",
94 "typesmapping",
95 "typesmethods",
96 "typesmodules",
97 "typesseq",
98 "typesseq-mutable",
99 "unary",
100 "while",
101 "with",
102 "yield",
103 })
104
105
106 class PydocTopicsBuilder(TextBuilder):
107 name = "pydoc-topics"
108
109 def init(self) -> None:
110 super().init()
111 self.topics: dict[str, str] = {}
112 self.module_docs: dict[str, str] = {}
113
114 def get_outdated_docs(self) -> str:
115 # Return a string describing what an update build will build.
116 return "all pydoc topics"
117
118 def write_documents(self, _docnames: Set[str]) -> None:
119 env = self.env
120
121 labels: dict[str, tuple[str, str, str]]
122 labels = env.domains.standard_domain.labels
123
124 # docname -> list of (topic_label, label_id) pairs
125 doc_labels: dict[str, list[tuple[str, str]]] = {}
126 for topic_label in _PYDOC_TOPIC_LABELS:
127 try:
128 docname, label_id, _section_name = labels[topic_label]
129 except KeyError:
130 logger.warning("label %r not in documentation", topic_label)
131 continue
132 doc_labels.setdefault(docname, []).append((topic_label, label_id))
133
134 py_domain = env.domains['py']
135 for module_name, module_info in py_domain.data['modules'].items():
136 docname = module_info[0]
137 if docname.startswith('library/'):
138 doc_file = docname.replace('library/', '')
139 self.module_docs[module_name] = (
140 f"{doc_file}#module-{module_name}"
141 )
142
143 for docname, label_ids in status_iterator(
144 doc_labels.items(),
145 "building topics... ",
146 length=len(doc_labels),
147 stringify_func=_display_labels,
148 ):
149 doctree = env.get_and_resolve_doctree(docname, builder=self)
150 doc_ids = doctree.ids
151 for topic_label, label_id in label_ids:
152 document = new_document("<section node>")
153 document.append(doc_ids[label_id])
154 visitor = TextTranslator(document, builder=self)
155 document.walkabout(visitor)
156 body = "\n".join(map(str.rstrip, visitor.body.splitlines()))
157 self.topics[topic_label] = body + "\n"
158
159 def finish(self) -> None:
160 topics_repr = "\n".join(
161 f" '{topic}': {_repr(self.topics[topic])},"
162 for topic in sorted(self.topics)
163 )
164 topics = f"""\
165 # Autogenerated by Sphinx on {asctime()}
166 # as part of the release process.
167
168 topics = {{
169 {topics_repr}
170 }}
171 """
172 self.outdir.joinpath("topics.py").write_text(topics, encoding="utf-8")
173
174 module_docs_repr = "\n".join(
175 f" '{module}': '{doc_file}',"
176 for module, doc_file in sorted(self.module_docs.items())
177 )
178 module_docs = f"""\
179 # Autogenerated by Sphinx on {asctime()}
180 # as part of the release process.
181
182 module_docs = {{
183 {module_docs_repr}
184 }}
185 """
186 self.outdir.joinpath("module_docs.py").write_text(
187 module_docs, encoding="utf-8"
188 )
189
190
191 def _display_labels(item: tuple[str, Sequence[tuple[str, str]]]) -> str:
192 _docname, label_ids = item
193 labels = [name for name, _id in label_ids]
194 if len(labels) > 4:
195 return f"{labels[0]}, {labels[1]}, ..., {labels[-2]}, {labels[-1]}"
196 return ", ".join(labels)
197
198
199 def _repr(text: str, /) -> str:
200 """Return a triple-single-quoted representation of text."""
201 if "'''" not in text:
202 return f"r'''{text}'''"
203 text = text.replace("\\", "\\\\").replace("'''", r"\'\'\'")
204 return f"'''{text}'''"
205
206
207 def setup(app: Sphinx) -> ExtensionMetadata:
208 app.add_builder(PydocTopicsBuilder)
209
210 return {
211 "version": "1.0",
212 "parallel_read_safe": True,
213 "parallel_write_safe": True,
214 }