mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-09 20:26:33 +00:00
kevinveenbirkenbachandClaude Opus 5
3b81b4de2e
apidoc now excludes roles/ and library/ the way it already excluded tests/. A role name carries hyphens and is therefore not an importable module path, so automodule reported 44 invalid signatures and rendered nothing; library/ holds ansible modules whose ansible.module_utils imports exist only inside a play. Measured: 168 generated pages drop to 151, and the 17 that go consist of a heading and automodule directives on unresolvable paths. The role page generator fits every section underline to its title. pandoc counts one character fewer than docutils where a heading ends in a stray variation selector left behind by a removed emoji. It also escapes inline markup in role metadata, because one description reads (*.parent) and opened an emphasis that never closed. The index generator underlined a 21-character caption with 19 characters. conf.py adds the tel scheme, without which the phone number in SECURITY.md is an unresolvable reference, and the extract copies the image assets into its conf directory the way the site builder does, without which every run reports a missing html_static_path and favicon. Four tests pinned values this changes. The fifth, the extension count in test_conf, asserted nothing the loop below it does not already prove and broke on every legitimate addition; it now asserts the list is non-empty, so that loop cannot run over nothing. With this, make i18n-extract domain=docs finishes with zero warnings under the -W gate. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
60 lines
1.8 KiB
Python
60 lines
1.8 KiB
Python
from __future__ import annotations
|
|
|
|
import argparse
|
|
import os
|
|
from pathlib import Path, PurePosixPath
|
|
|
|
|
|
def generate_ansible_roles_index(roles_dir, output_file, caption):
|
|
"""Write a toctree listing every ``.rst`` file in ``roles_dir``.
|
|
|
|
Args:
|
|
roles_dir: directory holding the generated role pages.
|
|
output_file: index file to write; entries are relative to its directory.
|
|
caption: page title and toctree caption.
|
|
"""
|
|
roles = Path(roles_dir).resolve()
|
|
output = Path(output_file).resolve()
|
|
if not roles.exists():
|
|
print(f"Error: Directory {roles} does not exist.")
|
|
return
|
|
output.parent.mkdir(parents=True, exist_ok=True)
|
|
|
|
entries = [
|
|
f" {PurePosixPath(os.path.relpath(roles / name, start=output.parent)).with_suffix('')}"
|
|
for name in sorted(
|
|
path.name for path in roles.iterdir() if path.suffix == ".rst"
|
|
)
|
|
]
|
|
lines = [
|
|
caption,
|
|
"=" * len(caption),
|
|
"",
|
|
".. toctree::",
|
|
" :maxdepth: 1",
|
|
f" :caption: {caption}",
|
|
"",
|
|
*entries,
|
|
]
|
|
output.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
|
print(f"Index generated at {output}")
|
|
|
|
|
|
def main(argv=None):
|
|
parser = argparse.ArgumentParser(description="Generate an index for documentation.")
|
|
parser.add_argument(
|
|
"--roles-dir", required=True, help="Directory containing .rst files."
|
|
)
|
|
parser.add_argument(
|
|
"--output-file", required=True, help="Path to the output index.rst file."
|
|
)
|
|
parser.add_argument("--caption", required=True, help="The index title")
|
|
args = parser.parse_args(argv)
|
|
|
|
generate_ansible_roles_index(args.roles_dir, args.output_file, args.caption)
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|