typedoc.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/docs/typedoc.py
 
"""
Purpose
-------
The TypeDoc tier of ``oct docs``: API documentation for TypeScript
subprojects, wired in the same shape as the Doxygen tier so the two are
learned once.
 
Doxygen has no TypeScript parser, and Sphinx autodoc has no TypeScript
either, so before this module a TypeScript subproject (``oc_explorer``)
had a Sphinx tier for its markdown and nothing for its API. TypeDoc runs
the real TypeScript compiler and documents the type-checked program, which
is why it beats any text-level tool for this job: generics, unions,
overloads, inferred return types and re-exports all come from the checker.
 
The declaration is a ``typedoc.json`` at the subproject root, mirroring
"the Doxyfile is the declaration": the single-project build runs on it,
the workspace fan-out includes the subproject on it, the hub shows a
TypeDoc card on it, and ``--clean`` sweeps the output regardless.
 
Responsibilities
----------------
- Own :data:`TYPEDOC_CONFIG_REL` and :func:`has_typedoc`, the declaration
  every consumer resolves.
- :func:`typedoc_output_dir` - read ``out`` from the config the way
  TypeDoc resolves it (relative to the config's directory).
- :func:`run_docs_typedoc` - clear the previous output, run TypeDoc via
  ``npx`` with the subproject as working directory, report the result.
 
Diagnostics
-----------
Domain: OCT-DOCS
Levels:
    L2 - build entry / exit
    L3 - tool resolution, output directory decision
    L4 - subprocess argv
 
Contracts
---------
- Nothing here installs anything. TypeDoc is a dev dependency of the
  TypeScript subproject (``npm install --save-dev typedoc``) and ``npx``
  resolves it from that subproject's ``node_modules``. A missing ``npx``
  is reported and returns non-zero from a direct ``--typedoc`` request,
  because the operator asked for that build by name; the workspace
  fan-out is the caller that decides whether that is fatal.
- Output is cleared before each run for the same reason Doxygen's is:
  a generator does not delete pages for inputs it no longer sees. The
  same two guards apply - the directory must resolve inside the project
  and must carry TypeDoc's own marker - so a mis-set ``out`` cannot turn
  a docs build into a recursive delete.
- No shell. The subprocess is an argv list; on Windows ``npx`` is a
  ``.cmd`` shim and is resolved through :func:`shutil.which` so the call
  works without ``shell=True``.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.tools.fs_remove (remove_tree_or_warn)
- oct.docs.workspace_docs (lazy; is_workspace_root, run_workspace_docs - the workspace fan-out)
"""
 
from __future__ import annotations
 
import json
import shutil
import subprocess
import sys
from pathlib import Path
 
from oct.core.diagnostics import _dbg
from oct.tools.fs_remove import remove_tree_or_warn
 
 
#: Where a project declares TypeDoc, relative to the project root.
TYPEDOC_CONFIG_REL: Path = Path("typedoc.json")
 
#: TypeDoc's default ``out`` when the config does not set one.
_DEFAULT_OUT: str = "docs"
 
#: Files TypeDoc writes into every HTML output directory it owns. One must
#: be present before the pre-run clear will delete the directory.
_TYPEDOC_HTML_MARKERS: tuple[str, ...] = ("index.html", "hierarchy.html", "assets")
 
 
def has_typedoc(project_dir: Path) -> bool:
    """Return True when *project_dir* declares TypeDoc documentation."""
    return (Path(project_dir) / TYPEDOC_CONFIG_REL).is_file()
 
 
def typedoc_output_dir(project_dir: Path) -> Path:
    """Resolve the HTML output directory the project's ``typedoc.json`` names.
 
    TypeDoc resolves a relative ``out`` against the directory holding the
    config file. A config that cannot be parsed, or that sets no ``out``,
    resolves to TypeDoc's default.
    """
    func = "typedoc_output_dir"
    config_path = Path(project_dir) / TYPEDOC_CONFIG_REL
    out = _DEFAULT_OUT
    try:
        data = json.loads(config_path.read_text(encoding="utf-8"))
        if isinstance(data, dict) and isinstance(data.get("out"), str) and data["out"]:
            out = data["out"]
    except (OSError, json.JSONDecodeError) as exc:
        _dbg("OCT-DOCS", func, f"config unreadable ({exc}); default out", 3)
    resolved = (config_path.parent / out).resolve()
    _dbg("OCT-DOCS", func, f"out={resolved}", 3)
    return resolved
 
 
def _clear_typedoc_output(project_dir: Path) -> None:
    """Delete the previous TypeDoc output, guarded the same way as Doxygen's."""
    func = "_clear_typedoc_output"
    html_dir = typedoc_output_dir(project_dir)
    if not html_dir.is_dir():
        return
    try:
        html_dir.relative_to(Path(project_dir).resolve())
    except ValueError:
        print(f"Warning: TypeDoc output {html_dir} is outside the project; "
              f"not clearing it.")
        _dbg("OCT-DOCS", func, f"refused: {html_dir} outside project", 2)
        return
    if not any((html_dir / m).exists() for m in _TYPEDOC_HTML_MARKERS):
        print(f"Warning: {html_dir} does not look like TypeDoc output "
              f"(no {_TYPEDOC_HTML_MARKERS[0]}); not clearing it.")
        _dbg("OCT-DOCS", func, f"refused: {html_dir} has no marker", 2)
        return
    if remove_tree_or_warn(html_dir, label="previous TypeDoc output"):
        _dbg("OCT-DOCS", func, f"cleared {html_dir}", 3)
 
 
def find_npx() -> str | None:
    """Return the ``npx`` executable path, or ``None`` when Node is absent.
 
    On Windows the launcher is ``npx.cmd``; :func:`shutil.which` finds
    either, and returning the resolved path lets the subprocess run as a
    plain argv list with no shell.
    """
    return shutil.which("npx")
 
 
def run_docs_typedoc(root: Path, *, no_workspace: bool = False) -> int:
    """Build the TypeDoc tier for the project at *root*.
 
    Returns 0 on success; 1 when the project declares no ``typedoc.json``,
    when ``npx`` cannot be found, or when TypeDoc itself fails.
 
    Workspace mode: from a workspace root, dispatches to
    :func:`oct.docs.workspace_docs.run_workspace_docs` with
    ``mode="typedoc"`` unless *no_workspace* is set.
    """
    func = "run_docs_typedoc"
    if not no_workspace:
        from oct.docs.workspace_docs import is_workspace_root, run_workspace_docs
        if is_workspace_root(root):
            return run_workspace_docs(root, mode="typedoc")
 
    _dbg("OCT-DOCS", func, f"start root={root}", 2)
    if not has_typedoc(root):
        print(
            f"Error: no {TYPEDOC_CONFIG_REL} at {root}.\n"
            f"A TypeScript project declares TypeDoc by carrying that file; "
            f"see 'oct docs --help'.",
            file=sys.stderr,
        )
        return 1
 
    npx = find_npx()
    if npx is None:
        print(
            "Error: npx is not on PATH. TypeDoc runs through Node.js; "
            "install Node and run 'npm install' in the project so its "
            "typedoc dev dependency is present.",
            file=sys.stderr,
        )
        _dbg("OCT-DOCS", func, "npx missing", 1)
        return 1
 
    _clear_typedoc_output(root)
 
    # --no-install: npx must find typedoc in the project's node_modules and
    # never fetch it from the registry mid-build. A missing dev dependency
    # is a project setup problem and should fail as one, not be papered
    # over by a network download that may or may not happen.
    argv = [npx, "--no-install", "typedoc"]
    _dbg("OCT-DOCS", func, f"argv={argv} cwd={root}", 4)
    print(f"Running typedoc (cwd {root})...")
    try:
        result = subprocess.run(argv, cwd=str(root))
    except OSError as exc:
        print(f"Error: could not run npx: {exc}", file=sys.stderr)
        return 1
 
    if result.returncode == 0:
        index = typedoc_output_dir(root) / "index.html"
        if index.exists():
            print(f"\nTypeDoc build complete. Open: {index}")
        else:
            print(f"\nTypeDoc build complete. Output: {typedoc_output_dir(root)}")
    _dbg("OCT-DOCS", func, f"end rc={result.returncode}", 2)
    return result.returncode
 
 
__all__ = [
    "TYPEDOC_CONFIG_REL",
    "find_npx",
    "has_typedoc",
    "run_docs_typedoc",
    "typedoc_output_dir",
]