mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-10 12:47:04 +00:00
kevinveenbirkenbachandClaude Opus 5
bed4b3c84f
cli/build/docs/integration_matrix was 1189 lines a human ran through 'make integration-matrix', and its output sat frozen as a 125-line grid in requirement 027. Its ENTITIES and EDGES lists were hand-maintained, so the grid could only drift: it covered 84 entities while the tree holds 98 roles, named two roles that no longer exist, and omitted sixteen current ones - api, checkmk, docs, hermes, homeassistant, jellyfin, meta, mirror, openbao, openclaw, penpot, pihole, s1, seaweedfs, seaweedfs-console and semaphore. infinito_docs/generators/integrations.py replaces it and joins the nine sibling generators in that package, so the overview, services and addons pages are written into generated/integrations/ on every docs build rather than when someone remembers the target. index.rst takes the overview and the new docs/architecture/integrations.rst references the other two. Requirement 027 becomes prose. The make target and its i8inma alias are removed as a pair, which keeps the alias lints satisfied. Coverage is not strictly larger. The removed EDGES list carried a curated upstream project URL per integration, 96 of them, and the new edges have no such field; only 48 of 159 addon declarations hold update.upstream_id or config.repository, so about a third is re-derivable and the rest existed only in that list. Its fourth field is no real loss - 57 entries read 'check', so it was a near-constant rather than an axis. In exchange the old module had zero tests, not one file under tests/ referenced it, and the generator ships 310 lines including generate(). Residuals: the HTML build runs without -W, but i18n.py:57 runs the gettext builder with -W and check=True, and that build has never seen integrations.rst - no catalog mentions generated/integrations. And docs/requirements/036:72 still carries a checked criterion asserting a table in 027 that no longer exists. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
139 lines
3.5 KiB
Python
139 lines
3.5 KiB
Python
"""The commands that build one version of the documentation and the progress they report."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
import sys
|
|
|
|
_STEP = re.compile(
|
|
r"^(reading sources|writing output|postprocess html)\.\.\. \[\s*(\d+)%\]"
|
|
)
|
|
_SPAN = {
|
|
"reading sources": (10, 40),
|
|
"writing output": (40, 60),
|
|
"postprocess html": (60, 99),
|
|
}
|
|
|
|
|
|
def _module(name, *args):
|
|
return [sys.executable, "-P", "-m", name, *(str(arg) for arg in args)]
|
|
|
|
|
|
def _generator(name, *args):
|
|
return _module(f"infinito_docs.generators.{name}", *args)
|
|
|
|
|
|
def generate_commands(src):
|
|
"""Return the commands that prepare ``src`` for ``sphinx-build``.
|
|
|
|
Args:
|
|
src: checkout of the version to document.
|
|
|
|
Returns:
|
|
argv lists, in the order they must run.
|
|
"""
|
|
generated = src / "generated"
|
|
return [
|
|
[
|
|
sys.executable,
|
|
"-m",
|
|
"sphinx.ext.apidoc",
|
|
"-f",
|
|
"-o",
|
|
str(generated / "modules"),
|
|
str(src),
|
|
str(src / "tests"),
|
|
str(src / "roles"),
|
|
str(src / "library"),
|
|
],
|
|
_generator(
|
|
"yaml_index",
|
|
"--source-dir",
|
|
src,
|
|
"--output-file",
|
|
generated / "yaml_index.rst",
|
|
),
|
|
_generator(
|
|
"ansible_roles",
|
|
"--roles-dir",
|
|
src / "roles",
|
|
"--output-dir",
|
|
generated / "roles",
|
|
),
|
|
_generator(
|
|
"index",
|
|
"--roles-dir",
|
|
generated / "roles",
|
|
"--output-file",
|
|
src / "roles" / "ansible_role_glosar.rst",
|
|
"--caption",
|
|
"Ansible Role Glossary",
|
|
),
|
|
_generator(
|
|
"roles_overview",
|
|
"--roles-dir",
|
|
src / "roles",
|
|
"--output-file",
|
|
generated / "roles_overview.json",
|
|
),
|
|
_generator(
|
|
"make_targets",
|
|
"--makefile",
|
|
src / "Makefile",
|
|
"--output-file",
|
|
generated / "make_targets.rst",
|
|
),
|
|
_generator(
|
|
"aliases",
|
|
"--aliases-file",
|
|
src / "aliases",
|
|
"--output-file",
|
|
generated / "aliases.rst",
|
|
),
|
|
_generator(
|
|
"cli_commands",
|
|
"--cli-dir",
|
|
src / "cli",
|
|
"--output-file",
|
|
generated / "cli_commands.rst",
|
|
),
|
|
_generator(
|
|
"integrations",
|
|
"--roles-dir",
|
|
src / "roles",
|
|
"--output-dir",
|
|
generated / "integrations",
|
|
),
|
|
_generator("readmes", "--generated-dir", generated),
|
|
_module(
|
|
"cli.build.docs.readme",
|
|
"--override",
|
|
"--roles-dir",
|
|
src / "roles",
|
|
),
|
|
_module(
|
|
"cli.build.docs.readme.overview",
|
|
"--readme",
|
|
src / "README.md",
|
|
"--roles-dir",
|
|
src / "roles",
|
|
),
|
|
]
|
|
|
|
|
|
def progress_of(line, current):
|
|
"""Return the overall build progress after one line of Sphinx output.
|
|
|
|
Args:
|
|
line: a line of ``sphinx-build`` output.
|
|
current: progress before this line, in percent.
|
|
|
|
Returns:
|
|
The new progress in percent; it never moves backwards.
|
|
"""
|
|
match = _STEP.match(line)
|
|
if not match:
|
|
return current
|
|
start, end = _SPAN[match.group(1)]
|
|
return max(current, start + (end - start) * int(match.group(2)) // 100)
|