Fourth stage refactor (aggregate documents)

python · AA-Turner · Jan 21, 2025 · Jan 21, 2025 · Jan 21, 2025 · Jan 21, 2025
commit 371755dd68c160984ef7a390ff4666251e216210
@@ -107,52 +107,63 @@
 class PydocTopicsBuilder(TextBuilder):
     name = 'pydoc-topics'
 
-    default_translator_class = TextTranslator
-
     def init(self) -> None:
+        super().init()
         self.topics: dict[str, str] = {}
 
     def get_outdated_docs(self) -> str:
         # Return a string describing what an update build will build.
         return 'all pydoc topics'
 
-    def get_target_uri(self, docname: str, typ: str | None = None) -> str:
-        return ''  # no URIs
-
     def write_documents(self, _docnames: Set[str]) -> None:
         env = self.env
 
         labels: dict[str, tuple[str, str, str]]
         labels = env.domains.standard_domain.labels
 
-        for label in status_iterator(
-            _PYDOC_TOPIC_LABELS,
-            'building topics... ',
-            length=len(_PYDOC_TOPIC_LABELS),
-        ):
+        # docname -> list of (topic_label, label_id) pairs
+        doc_labels: dict[str, list[tuple[str, str]]] = {}
+        for topic_label in _PYDOC_TOPIC_LABELS:
             try:
-                docname, label_id, _section_name = labels[label]
+                docname, label_id, _section_name = labels[topic_label]
             except KeyError:
-                logger.warning('label %r not in documentation', label)
+                logger.warning('label %r not in documentation', topic_label)
                 continue
+            doc_labels.setdefault(docname, []).append((topic_label, label_id))
 
+        for docname, label_ids in status_iterator(
+            doc_labels.items(),
+            'building topics... ',
+            length=len(doc_labels),
+            stringify_func=_display_labels,
+        ):
             doctree = env.get_and_resolve_doctree(docname, builder=self)
-            document = new_document('<section node>')
-            document.append(doctree.ids[label_id])
-            visitor = TextTranslator(document, builder=self)
-            document.walkabout(visitor)
-            self.topics[label] = visitor.body
+            doc_ids = doctree.ids
+            for topic_label, label_id in label_ids:
+                document = new_document('<section node>')
+                document.append(doc_ids[label_id])
+                visitor = TextTranslator(document, builder=self)
+                document.walkabout(visitor)
+                self.topics[topic_label] = visitor.body
 
     def finish(self) -> None:
         topics = f'''\
 # Autogenerated by Sphinx on {asctime()}
 # as part of the release process.
 
-topics = {pformat(self.topics)}
+topics = {pformat(dict(sorted(self.topics.items())))}
 '''
         self.outdir.joinpath('topics.py').write_text(topics, encoding='utf-8')
 
 
+def _display_labels(item: tuple[str, Sequence[tuple[str, str]]]) -> str:
+    _docname, label_ids = item
+    labels = [name for name, _id in label_ids]
+    if len(labels) > 4:
+        return f'{labels[0]}, {labels[1]}, ..., {labels[-2]}, {labels[-1]}'
+    return ', '.join(labels)
+
+
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(PydocTopicsBuilder)