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