#!/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())