|
| 1 | +#!/usr/bin/env python3 |
| 2 | +""" |
| 3 | +Generate API documentation using Sphinx + AutoAPI. |
| 4 | +
|
| 5 | +This script builds HTML docs into docs/_build/html. |
| 6 | +It avoids importing the package by relying on sphinx-autoapi |
| 7 | +to parse source files directly. |
| 8 | +""" |
| 9 | + |
| 10 | +import shutil |
| 11 | +import os |
| 12 | +import sys |
| 13 | +from pathlib import Path |
| 14 | +import importlib |
| 15 | + |
| 16 | + |
| 17 | +def ensure_tools_available() -> None: |
| 18 | + try: |
| 19 | + importlib.import_module("sphinx") |
| 20 | + importlib.import_module("autoapi") |
| 21 | + importlib.import_module("myst_parser") |
| 22 | + except Exception as exc: |
| 23 | + root = Path(__file__).resolve().parents[1] |
| 24 | + req = root / "requirements-dev.txt" |
| 25 | + print( |
| 26 | + "Missing documentation dependencies. " |
| 27 | + f"Install with: python3 -m pip install -r {req}", |
| 28 | + file=sys.stderr, |
| 29 | + ) |
| 30 | + raise SystemExit(1) from exc |
| 31 | + |
| 32 | + |
| 33 | +def build_docs() -> None: |
| 34 | + root = Path(__file__).resolve().parents[1] |
| 35 | + docs_dir = root / "api-docs" |
| 36 | + build_dir = docs_dir / "_build" / "html" |
| 37 | + api_dir = docs_dir / "api" |
| 38 | + |
| 39 | + # Preprocess sources: convert Markdown code fences in docstrings to reST |
| 40 | + src_pkg_dir = root / "src" / "c2pa" |
| 41 | + pre_dir = docs_dir / "_preprocessed" |
| 42 | + pre_pkg_dir = pre_dir / "c2pa" |
| 43 | + if pre_dir.exists(): |
| 44 | + shutil.rmtree(pre_dir) |
| 45 | + pre_pkg_dir.mkdir(parents=True, exist_ok=True) |
| 46 | + |
| 47 | + def convert_fences_to_rst(text: str) -> str: |
| 48 | + lines = text.splitlines() |
| 49 | + out: list[str] = [] |
| 50 | + i = 0 |
| 51 | + while i < len(lines): |
| 52 | + line = lines[i] |
| 53 | + stripped = line.lstrip() |
| 54 | + indent = line[: len(line) - len(stripped)] |
| 55 | + if stripped.startswith("```"): |
| 56 | + fence = stripped |
| 57 | + lang = fence[3:].strip() or "text" |
| 58 | + # Start directive |
| 59 | + out.append(f"{indent}.. code-block:: {lang}") |
| 60 | + out.append("") |
| 61 | + i += 1 |
| 62 | + # Emit indented code until closing fence |
| 63 | + while i < len(lines): |
| 64 | + l2 = lines[i] |
| 65 | + if l2.lstrip().startswith("```"): |
| 66 | + i += 1 |
| 67 | + break |
| 68 | + out.append(f"{indent} {l2}") |
| 69 | + i += 1 |
| 70 | + continue |
| 71 | + out.append(line) |
| 72 | + i += 1 |
| 73 | + return "\n".join(out) + ("\n" if text.endswith("\n") else "") |
| 74 | + |
| 75 | + for src_path in src_pkg_dir.rglob("*.py"): |
| 76 | + rel = src_path.relative_to(src_pkg_dir) |
| 77 | + dest = pre_pkg_dir / rel |
| 78 | + dest.parent.mkdir(parents=True, exist_ok=True) |
| 79 | + content = src_path.read_text(encoding="utf-8") |
| 80 | + dest.write_text(convert_fences_to_rst(content), encoding="utf-8") |
| 81 | + |
| 82 | + # Point AutoAPI to preprocessed sources |
| 83 | + os.environ["C2PA_DOCS_SRC"] = str(pre_pkg_dir) |
| 84 | + |
| 85 | + # Clean AutoAPI output to avoid stale pages |
| 86 | + if api_dir.exists(): |
| 87 | + shutil.rmtree(api_dir) |
| 88 | + |
| 89 | + build_dir.mkdir(parents=True, exist_ok=True) |
| 90 | + |
| 91 | + try: |
| 92 | + sphinx_build_mod = importlib.import_module("sphinx.cmd.build") |
| 93 | + sphinx_main = getattr(sphinx_build_mod, "main") |
| 94 | + code = sphinx_main([ |
| 95 | + "-b", |
| 96 | + "html", |
| 97 | + str(docs_dir), |
| 98 | + str(build_dir), |
| 99 | + ]) |
| 100 | + if code != 0: |
| 101 | + raise SystemExit(code) |
| 102 | + except Exception: |
| 103 | + # Fallback to subprocess if needed |
| 104 | + import subprocess |
| 105 | + |
| 106 | + cmd = [ |
| 107 | + sys.executable, |
| 108 | + "-m", |
| 109 | + "sphinx", |
| 110 | + "-b", |
| 111 | + "html", |
| 112 | + str(docs_dir), |
| 113 | + str(build_dir), |
| 114 | + ] |
| 115 | + subprocess.run(cmd, check=True) |
| 116 | + |
| 117 | + print(f"API docs generated at: {build_dir}") |
| 118 | + |
| 119 | + |
| 120 | +if __name__ == "__main__": |
| 121 | + ensure_tools_available() |
| 122 | + build_docs() |
| 123 | + |
| 124 | + |
0 commit comments