91 lines
2.8 KiB
Python
91 lines
2.8 KiB
Python
|
#!/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())
|