77 lines
2.0 KiB
Python
77 lines
2.0 KiB
Python
"""Utilities to support sub-indices for PEPs."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import os
|
|
from pathlib import Path
|
|
from typing import TYPE_CHECKING
|
|
|
|
from pep_sphinx_extensions.pep_zero_generator import writer
|
|
|
|
if TYPE_CHECKING:
|
|
from sphinx.environment import BuildEnvironment
|
|
|
|
from pep_sphinx_extensions.pep_zero_generator.parser import PEP
|
|
|
|
|
|
def update_sphinx(filename: str, text: str, docnames: list[str], env: BuildEnvironment) -> Path:
|
|
file_path = Path(env.srcdir, f"{filename}.rst")
|
|
file_path.write_text(text, encoding="utf-8")
|
|
|
|
# Add to files for builder
|
|
docnames.append(filename)
|
|
# Add to files for writer
|
|
env.found_docs.add(filename)
|
|
|
|
return file_path
|
|
|
|
|
|
def generate_subindices(
|
|
subindices: dict[str, str],
|
|
peps: list[PEP],
|
|
docnames: list[str],
|
|
env: BuildEnvironment,
|
|
) -> None:
|
|
# create topic directory
|
|
os.makedirs(os.path.join(env.srcdir, "topic"), exist_ok=True)
|
|
|
|
# Create sub index page
|
|
generate_topic_contents(docnames, env)
|
|
|
|
for subindex, additional_description in subindices.items():
|
|
header_text = f"{subindex.title()} PEPs"
|
|
header_line = "#" * len(header_text)
|
|
header = header_text + "\n" + header_line + "\n"
|
|
|
|
topic = subindex.lower()
|
|
filtered_peps = [pep for pep in peps if topic in pep.topic]
|
|
subindex_intro = f"""\
|
|
This is the index of all Python Enhancement Proposals (PEPs) labelled
|
|
under the '{subindex.title()}' topic. This is a sub-index of :pep:`0`,
|
|
the PEP index.
|
|
|
|
{additional_description}
|
|
"""
|
|
subindex_text = writer.PEPZeroWriter().write_pep0(
|
|
filtered_peps, header, subindex_intro, is_pep0=False,
|
|
)
|
|
update_sphinx(f"topic/{subindex}", subindex_text, docnames, env)
|
|
|
|
|
|
def generate_topic_contents(docnames: list[str], env: BuildEnvironment):
|
|
update_sphinx("topic/index", """\
|
|
.. _topic-index:
|
|
|
|
Topic Index
|
|
***********
|
|
|
|
PEPs are indexed by topic on the pages below:
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:titlesonly:
|
|
:glob:
|
|
|
|
*
|
|
""", docnames, env)
|