mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-09 20:26:33 +00:00
kevinveenbirkenbachandClaude Opus 5
6eb9a59d14
The Sphinx configuration, extensions and generators lived in the separate infinito-sphinx repository, whose image baked a snapshot of core at build time from a base image name core no longer publishes. Only core consumed it, and its generators read core's role layout, so the two repositories drifted without any CI covering the pair. The tooling now ships in roles/web-app-docs/files/, and web-app-sphinx is renamed to web-app-docs. The container is a small service instead of a static image: - it keeps a git mirror of the repository in the docs_sites volume; - /latest/ is the last commit of the default branch, rebuilt whenever a fetch finds a new one while the previous build stays online; - every release tag is selectable in the sidebar switcher and on /versions/, and is built the first time someone opens it, behind a progress bar; - replicas share the volume: the one holding builder.lock fetches and builds, the queue and the build states are files beside the sites, so another replica resumes the queue when the builder dies. The theme rewrites every page serially after the build, which took about 75 minutes for the 4544 pages; that pass now runs on the -j workers with the theme's own function. sphinx-apidoc skips tests/, because tests/utils/bare_bootstrap_probe.py installs an import blocker when autodoc imports it and killed the Sphinx workers. The roles overview is generated by a separate process, so autodoc resolves utils from the version being built, not from main. The role pages now show galaxy_info.description instead of the top-level key that never existed. The Sphinx packages join the dev extra, because the mirrored unit tests of the tooling import them. min_storage now budgets the built image, the latest site and a running build's scratch instead of the old image's size. The Playwright suite is split into front page, versions and on-demand build files; the last one selects an unbuilt tag in the overview and asserts the build gets queued. Operators must rename the web-app-sphinx inventory group to web-app-docs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
100 lines
2.8 KiB
Python
100 lines
2.8 KiB
Python
from __future__ import annotations
|
|
|
|
import logging
|
|
import re
|
|
from itertools import pairwise
|
|
from pathlib import Path
|
|
|
|
DEFAULT_MAX_NAV_DEPTH = 4
|
|
MAX_HEADING_LEVEL = 0
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
_MD_HEADING = re.compile(r"^(#+)(.*?)$")
|
|
_RST_UNDERLINE = re.compile(r"[-=~^+\"'`]+")
|
|
|
|
|
|
def natural_sort_key(text):
|
|
return [int(c) if c.isdigit() else c.lower() for c in re.split(r"(\d+)", text)]
|
|
|
|
|
|
def _markdown_headings(lines, max_level):
|
|
headings = []
|
|
in_code_block = False
|
|
for line in lines:
|
|
if line.strip().startswith("```"):
|
|
in_code_block = not in_code_block
|
|
continue
|
|
match = None if in_code_block else _MD_HEADING.match(line)
|
|
if match and len(match.group(1)) <= max_level:
|
|
text = match.group(2).strip()
|
|
anchor = re.sub(r"[^a-z0-9\-]", "", re.sub(r"\s+", "-", text.lower()))
|
|
headings.append(
|
|
{"level": len(match.group(1)), "text": text, "anchor": anchor}
|
|
)
|
|
return headings
|
|
|
|
|
|
def _rst_headings(lines):
|
|
return [
|
|
{"level": 1, "text": text.strip(), "anchor": ""}
|
|
for text, underline in pairwise(lines)
|
|
if len(underline) >= 3 and _RST_UNDERLINE.fullmatch(underline)
|
|
]
|
|
|
|
|
|
def extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL):
|
|
"""Return the headings of a Markdown or reStructuredText file.
|
|
|
|
Args:
|
|
filepath: file to scan.
|
|
max_level: deepest Markdown heading level to keep; ``0`` keeps all.
|
|
|
|
Returns:
|
|
``{"level", "text", "anchor"}`` dicts in file order. An ``index.rst``
|
|
without headings falls back to the ``README.md`` beside it.
|
|
"""
|
|
path = Path(filepath)
|
|
try:
|
|
lines = path.read_text(encoding="utf-8").splitlines()
|
|
except (OSError, UnicodeDecodeError) as exc:
|
|
logger.warning("Error reading %s: %s", path, exc)
|
|
lines = []
|
|
|
|
suffix = path.suffix.lower()
|
|
if suffix == ".md":
|
|
headings = _markdown_headings(lines, max_level or 9999)
|
|
elif suffix == ".rst":
|
|
headings = _rst_headings(lines)
|
|
else:
|
|
headings = []
|
|
|
|
readme = path.with_name("README.md")
|
|
if not headings and path.name.lower() == "index.rst" and readme.is_file():
|
|
return extract_headings_from_file(readme, max_level)
|
|
return headings
|
|
|
|
|
|
def group_headings(headings):
|
|
tree = []
|
|
stack = []
|
|
for heading in headings:
|
|
heading["children"] = []
|
|
while stack and stack[-1]["level"] >= heading["level"]:
|
|
stack.pop()
|
|
(stack[-1]["children"] if stack else tree).append(heading)
|
|
stack.append(heading)
|
|
return tree
|
|
|
|
|
|
def sort_tree(tree):
|
|
tree.sort(
|
|
key=lambda x: (
|
|
x.get("priority", 1),
|
|
natural_sort_key(x.get("filename", x["text"])),
|
|
)
|
|
)
|
|
for item in tree:
|
|
if item.get("children"):
|
|
sort_tree(item["children"])
|