Утилита для упрощения генерации доков

SRV/utils/build_docs.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+Утилита для сборки Sphinx-документации проекта GONETS.
+
+Позволяет из корня каталога `SRV/` одним запуском пересобрать HTML и Markdown
+версии документации. Пример использования:
+
+    poetry run python utils/build_docs.py
+
+По умолчанию собираются оба билда (`html` и `markdown`). Повторные вызовы
+перезаписывают существующий вывод Sphinx.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Iterable, List
+
+from sphinx.cmd.build import build_main
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+DOCS_DIR = ROOT_DIR / "docs"
+BUILD_ROOT = DOCS_DIR / "_build"
+
+
+def build_docs(builders: Iterable[str]) -> None:
+    """
+    Вызывает Sphinx для каждого указанного билдера.
+
+    Args:
+        builders: последовательность имён билдов Sphinx (например, ["html"]).
+
+    Raises:
+        RuntimeError: если сборка для какого-либо билдера завершилась с ошибкой.
+    """
+    for builder in builders:
+        output_dir = BUILD_ROOT / builder
+        output_dir.parent.mkdir(parents=True, exist_ok=True)
+
+        args: List[str] = [
+            "-b",
+            builder,
+            str(DOCS_DIR),
+            str(output_dir),
+        ]
+        print(f"[build-docs] sphinx-build {' '.join(args)}")
+
+        exit_code = build_main(args)
+        if exit_code != 0:
+            raise RuntimeError(
+                f"Sphinx build failed for builder '{builder}' with exit code {exit_code}"
+            )
+
+
+def parse_args(argv: Iterable[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Сборка документации проекта GONETS (Sphinx)."
+    )
+    parser.add_argument(
+        "-b",
+        "--builder",
+        action="append",
+        choices=("html", "markdown"),
+        help="Ограничить сборку указанными билдерами (по умолчанию html и markdown).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    args = parse_args(argv or sys.argv[1:])
+    builders = args.builder or ["html", "markdown"]
+
+    if not DOCS_DIR.exists():
+        print(f"[build-docs] docs directory not found: {DOCS_DIR}", file=sys.stderr)
+        return 1
+
+    try:
+        build_docs(builders)
+    except RuntimeError as exc:
+        print(f"[build-docs] {exc}", file=sys.stderr)
+        return 1
+
+    print("[build-docs] Documentation build completed successfully")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())