8000 GH-121970: Extract ``pydoc_topics`` into a new extension by AA-Turner · Pull Request #129116 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

GH-121970: Extract pydoc_topics into a new extension #129116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jan 21, 2025
Merged

GH-121970: Extract pydoc_topics into a new extension #129116

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
192eac8
Extract ``pydoc_topics`` into a new extension
AA-Turner Jan 21, 2025
d44ad65
Initial refactor (format, lint, type annotations, pathlib)
AA-Turner Jan 21, 2025
c78578b
Second stage refactor
AA-Turner Jan 21, 2025
fe0a5dc
Third stage refactor (use TextTranslator directly)
AA-Turner Jan 21, 2025
371755d
Fourth stage refactor (aggregate documents)
AA-Turner Jan 21, 2025
e27c60a
double quotes
AA-Turner Jan 21, 2025
1d278ae
Use a triple single quote representation
AA-Turner Jan 21, 2025
5ac0ac4
Update ``Lib/pydoc_data/topics.py``
AA-Turner Jan 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Second stage refactor
  • Loading branch information
@AA-Turner
AA-Turner committed Jan 21, 2025
commit c78578bcdbe57415dc92ee6d6acd86271dd0a74e
36 changes: 20 additions & 16 deletions Doc/tools/extensions/pydoc_topics.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,20 @@
from typing import TYPE_CHECKING

from docutils.io import StringOutput
from docutils.utils import new_document
from sphinx.builders import Builder
from sphinx.builders.text import TextBuilder
from sphinx.util import logging
from sphinx.util.display import status_iterator
from sphinx.util.docutils import new_document
from sphinx.writers.text import TextTranslator, TextWriter

if TYPE_CHECKING:
from collections.abc import Sequence
from collections.abc import Sequence, Set

from sphinx.application import Sphinx
from sphinx.util.typing import ExtensionMetadata

logger = logging.getLogger(__name__)

_PYDOC_TOPIC_LABELS: Sequence[str] = sorted({
'assert',
'assignment',
Expand Down Expand Up @@ -102,7 +105,7 @@
})


class PydocTopicsBuilder(Builder):
class PydocTopicsBuilder(TextBuilder):
name = 'pydoc-topics'

default_translator_class = TextTranslator
Expand All @@ -117,26 +120,27 @@ def get_outdated_docs(self) -> str:
def get_target_uri(self, docname: str, typ: str | None = None) -> str:
return '' # no URIs

def write(self, *ignored) -> None:
def write_documents(self, _docnames: Set[str]) -> None:
env = self.env

labels: dict[str, tuple[str, str, str]]
labels = env.domains.standard_domain.labels

writer = TextWriter(self)
for label in status_iterator(
_PYDOC_TOPIC_LABELS,
'building topics... ',
length=len(_PYDOC_TOPIC_LABELS),
):
if label not in self.env.domaindata['std']['labels']:
self.env.logger.warning(
f'label {label!r} not in documentation'
)
try:
docname, label_id, _section_name = labels[label]
except KeyError:
logger.warning('label %r not in documentation', label)
continue
docname, labelid, _sectname = self.env.domaindata['std']['labels'][
label
]
doctree = self.env.get_and_resolve_doctree(docname, self)
doctree = env.get_and_resolve_doctree(docname, builder=self)
document = new_document('<section node>')
document.append(doctree.ids[labelid])
destination = StringOutput(encoding='utf-8')
writer.write(document, destination)
document.append(doctree.ids[label_id])
writer.write(document, StringOutput(encoding='unicode'))
self.topics[label] = writer.output

def finish(self) -> None:
Expand Down
0