90 lines
2.8 KiB
Python
90 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())
|