workspace_docs.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/docs/workspace_docs.py
 
"""
Purpose
-------
Workspace-mode orchestrator for ``oct docs``. When the docs command is
invoked from a workspace root (a directory containing
``.option_c_workspace.json``), this module fans out the build across
each subproject, builds the workspace-tier "Option C" Sphinx tree from
the spec markdown, and aggregates everything under
``<workspace>/_site/`` with a Jinja-rendered front page.
 
Single-project invocations (from inside ``oct/`` or ``oc_diagnostics/``,
or from any non-workspace directory) bypass this module entirely - the
existing single-project pipelines in :mod:`oct.docs.oct_docs` handle
those unchanged.
 
Responsibilities
----------------
- Detect workspace mode at the dispatcher boundary and refuse to run
  outside a real workspace root.
- Walk ``workspace.subprojects`` from the manifest and invoke the
  single-project Sphinx / Doxygen pipelines for each, suppressing
  recursion via ``no_workspace=True``. A subproject whose manifest entry
  sets ``html_docs: false`` is skipped and its aggregated output
  withdrawn; ``--clean`` still sweeps it, because opting out of building
  is not opting out of tidying up.
- Keep a subproject's Doxygen off the site when its manifest entry sets
  ``html_docs: {"doxygen": false}`` (2026-09-28) or it has no Doxyfile:
  the fan-out neither builds nor aggregates it, and any
  ``_site/<sp>/doxygen/`` an earlier run left is withdrawn in every build
  mode. A direct ``oct docs --doxygen`` inside the subproject is not
  routed through here and still builds.
- Build the Option C tier Sphinx tree from
  ``<workspace>/docs/option_c_specs/*.md`` plus the workspace
  ``README.md`` as the toctree root (Phase D).
- Aggregate every per-subproject ``docs/_build/html/`` into
  ``_site/<sp>/sphinx/html/``; same for Doxygen output.
- Render the front page via :mod:`oct.docs.front_page` (Phase B).
- Implement ``--clean`` semantics that strip ``_site/`` and every
  subproject's ``docs/_build/`` (Phase F).
 
Diagnostics
-----------
Domain: OCT-DOCS
Levels:
    L2 - orchestrator entry / exit, mode dispatch
    L3 - per-subproject build dispatch, aggregation steps
    L4 - per-file copy decisions
 
Contracts
---------
- ``run_workspace_docs`` is the single entry point. It must never be
  called from inside a subproject root - the dispatcher in
  :mod:`oct.docs.oct_docs` is responsible for that gate.
- The function returns a non-zero exit code on any sub-build failure;
  failures in one subproject do not abort the others, so the user sees
  every problem in one run.
- Aggregation uses :func:`shutil.copytree` not symlinks (Windows-safe).
 
Dependencies
------------
- oct.core.workspace (manifest loader, find_workspace_root)
- oct.core.diagnostics (_dbg structured logger)
- oct.tools.fs_remove (remove_tree_or_warn - clears aggregated and generated output, warning on a tree that will not go)
- oct.docs.front_page (lazy; render_front_page, FrontPageError - the hub front page)
- oct.docs.oct_docs (lazy; run_docs_sphinx, run_docs_doxygen, _find_doxyfile - the single-project pipelines)
- oct.docs.option_c_tier (lazy; build_option_c_tier - the workspace-tier Option C Sphinx tree)
- oct.docs.typedoc (lazy; has_typedoc, run_docs_typedoc, typedoc_output_dir - the TypeDoc tier)
"""
 
from __future__ import annotations
 
import shutil
from pathlib import Path
from typing import Literal
 
from oct.core.diagnostics import _dbg
from oct.tools.fs_remove import remove_tree_or_warn
from oct.core.workspace import (
    Subproject,
    Workspace,
    WorkspaceError,
    find_workspace_root,
    load_workspace,
)
 
 
WorkspaceDocsMode = Literal["sphinx", "doxygen", "typedoc", "all", "clean"]
 
 
#: Aggregation directory relative to the workspace root.
SITE_DIRNAME: str = "_site"
 
#: Where each subproject's Sphinx HTML lives after a single-project build
#: (matches :func:`oct.docs.oct_docs.run_sphinx_build` output convention).
_SPHINX_BUILD_REL: Path = Path("docs") / "html"
 
#: Where each subproject's Doxygen HTML lives.
_DOXYGEN_BUILD_REL: Path = Path("docs") / "doxygen_output" / "html"
 
 
def is_workspace_root(path: Path) -> bool:
    """Return True iff *path* is the root of an Option C workspace.
 
    A workspace root holds a ``.option_c_workspace.json`` manifest
    *directly* (not inherited from a parent). This is the gate the
    dispatcher uses to decide whether to route to
    :func:`run_workspace_docs`.
    """
    func = "is_workspace_root"
    ws = find_workspace_root(path)
    matches = ws is not None and ws.resolve() == path.resolve()
    _dbg("OCT-DOCS", func, f"path={path} match={matches}", 4)
    return matches
 
 
def _doxygen_withheld(sp: Subproject) -> str | None:
    """Return why *sp* has no Doxygen on the site, or ``None`` when it has.
 
    Two causes share one consequence. The manifest switch
    ``html_docs: {"doxygen": false}`` keeps a declared Doxygen tier off the
    site, and a subproject with no Doxyfile has no Doxygen tier to publish.
    Either way the fan-out builds nothing and aggregates nothing, and any
    tree an earlier run left under ``_site/<sp>/doxygen/`` is withdrawn, so
    one answer serves the build step and the aggregation step alike. The
    reason is worded to follow ``has`` in the printed line.
    """
    if not sp.html_docs_doxygen:
        return "html_docs.doxygen=false"
    from oct.docs.oct_docs import _find_doxyfile
    if _find_doxyfile(sp.path) is None:
        return "no Doxyfile"
    return None
 
 
def _build_subproject(
    sp: Subproject,
    *,
    mode: WorkspaceDocsMode,
) -> int:
    """Run the single-project pipeline for *sp* in ``no_workspace`` mode.
 
    Returns the per-build exit code so the caller can aggregate. A subproject
    with no ``docs/doxygen_work_dir/Doxyfile``, or whose manifest entry sets
    ``html_docs: {"doxygen": false}``, has its Doxygen step SKIPPED rather
    than failed - see the comment at that branch.
    """
    func = "_build_subproject"
    _dbg("OCT-DOCS", func, f"sp={sp.name} mode={mode}", 3)
    rc = 0
    if mode in ("sphinx", "all"):
        from oct.docs.oct_docs import run_docs_sphinx
        sphinx_rc = run_docs_sphinx(sp.path, no_workspace=True)
        if sphinx_rc != 0:
            print(f"[workspace docs] subproject '{sp.name}' Sphinx failed (rc={sphinx_rc})")
            rc = rc or sphinx_rc
    if mode in ("doxygen", "all"):
        from oct.docs.oct_docs import run_docs_doxygen
        # A subproject with no Doxyfile is not a Doxygen subproject, and saying
        # "failed" about a build nobody asked for is a false alarm that made the
        # whole workspace run non-zero (eight of twelve subprojects here). The
        # Doxyfile's presence IS the declaration, so a new subproject can be
        # registered without a C/C++ doc toolchain and without breaking the docs
        # system. Announced rather than silent: a Doxyfile that ought to be there
        # and is not must still be visible in the log.
        #
        # This is deliberately the WORKSPACE fan-out only. A direct
        # ``oct docs --doxygen`` in a single project still fails loudly, because
        # there the operator asked for a Doxygen build by name and an empty
        # success would be a lie.
        #
        # The manifest switch html_docs.doxygen=false skips the step the same
        # way for a subproject that does have a Doxyfile: its output is not
        # wanted on the site, so building it here would only cost time. The
        # direct single-project ask still builds, which is how the output is
        # inspected while it is being tuned.
        withheld = _doxygen_withheld(sp)
        if withheld is not None:
            print(f"[workspace docs] subproject '{sp.name}' has {withheld} "
                  f"- skipping Doxygen")
            _dbg("OCT-DOCS", func, f"sp={sp.name} doxygen skipped ({withheld})", 3)
        else:
            dox_rc = run_docs_doxygen(sp.path, no_workspace=True)
            if dox_rc != 0:
                print(f"[workspace docs] subproject '{sp.name}' Doxygen failed (rc={dox_rc})")
                rc = rc or dox_rc
    if mode in ("typedoc", "all"):
        from oct.docs.typedoc import find_npx, has_typedoc, run_docs_typedoc
        # Same declaration model as Doxygen: typedoc.json present means the
        # subproject wants the tier, absent means it is not a TypeScript
        # subproject and there is nothing to say. Node missing on the docs
        # machine is a skip with a notice here rather than a failure, so a
        # Python-only docs host still completes the workspace build; the
        # direct --typedoc request in the single-project path fails loudly.
        if not has_typedoc(sp.path):
            _dbg("OCT-DOCS", func, f"sp={sp.name} typedoc skipped (no typedoc.json)", 4)
        elif find_npx() is None:
            print(f"[workspace docs] subproject '{sp.name}' declares TypeDoc "
                  f"but npx is not on PATH - skipping TypeDoc")
            _dbg("OCT-DOCS", func, f"sp={sp.name} typedoc skipped (no npx)", 3)
        else:
            td_rc = run_docs_typedoc(sp.path, no_workspace=True)
            if td_rc != 0:
                print(f"[workspace docs] subproject '{sp.name}' TypeDoc failed (rc={td_rc})")
                rc = rc or td_rc
    _dbg("OCT-DOCS", func, f"sp={sp.name} rc={rc}", 3)
    return rc
 
 
def _copytree_replace(src: Path, dst: Path) -> None:
    """Replace *dst* with a fresh copy of *src*.
 
    No-op when *src* does not exist (allows partial builds - e.g. a
    subproject that has only Sphinx, not Doxygen).
    """
    func = "_copytree_replace"
    if not src.exists():
        _dbg("OCT-DOCS", func, f"skip {src} -> {dst} (src missing)", 4)
        return
    # A *dst* that will not go would make ``copytree`` raise FileExistsError
    # onto the aggregate. Copy into what remains instead of abandoning it: a
    # recursive delete works bottom-up, so a refusal at the final rmdir has
    # ALREADY taken the files and left the directory shell. The fresh output is
    # what the caller asked for; what can survive is a file this build no longer
    # produces, which is why the difference is printed rather than swallowed.
    cleared = True
    if dst.exists():
        cleared = remove_tree_or_warn(dst, label="stale aggregated output")
        if not cleared:
            print(f"  note: {dst} could not be cleared first; copying into it. "
                  f"Files this build no longer produces may survive there.")
    dst.parent.mkdir(parents=True, exist_ok=True)
    shutil.copytree(src, dst, dirs_exist_ok=not cleared)
    _dbg("OCT-DOCS", func, f"copied {src} -> {dst} (cleared={cleared})", 4)
 
 
def _aggregate(
    ws_root: Path,
    workspace: Workspace,
    *,
    mode: WorkspaceDocsMode,
) -> Path:
    """Copy each subproject's HTML into ``<ws_root>/_site/<sp>/<tool>/html/``,
    plus the workspace-tier Option C Sphinx output into ``_site/option_c/``.
 
    A subproject with ``html_docs=false`` loses its whole ``_site/<sp>/``
    tree; one whose Doxygen is withheld (see :func:`_doxygen_withheld`)
    loses only ``_site/<sp>/doxygen/``, plus ``_site/<sp>/`` itself when
    that withdrawal leaves it empty. Both withdrawals run in every mode.
 
    Returns the resolved site root.
    """
    func = "_aggregate"
    site_root = ws_root / SITE_DIRNAME
    site_root.mkdir(parents=True, exist_ok=True)
    _dbg("OCT-DOCS", func, f"site_root={site_root} mode={mode}", 3)
 
    for sp in workspace.subprojects:
        if not sp.html_docs:
            # Nothing was built, so there is nothing to copy - but an earlier
            # run (before the manifest opted this subproject out) may have left
            # a tree behind, and leaving it would serve stale pages at a live
            # URL. Withdrawing the declaration has to withdraw the output.
            stale = site_root / sp.name
            if stale.exists():
                print(f"[workspace docs] subproject '{sp.name}' has "
                      f"html_docs=false - removing its aggregated output")
                remove_tree_or_warn(stale, label="withdrawn aggregated output")
            _dbg("OCT-DOCS", func, f"sp={sp.name} aggregation skipped (html_docs=false)", 3)
            continue
        if mode in ("sphinx", "all"):
            _copytree_replace(
                sp.path / _SPHINX_BUILD_REL,
                site_root / sp.name / "sphinx" / "html",
            )
        withheld = _doxygen_withheld(sp)
        if withheld is not None:
            # The html_docs=false rule above, one tier down. It runs in every
            # build mode, not only doxygen and all, because the hub is
            # re-rendered on every run and drops the Doxygen card at once; a
            # tree left behind would stay served at a URL nothing links to.
            # Local docs/doxygen_output/ is left alone: that is the direct
            # single-project build, which the switch does not govern.
            stale_dox = site_root / sp.name / "doxygen"
            if stale_dox.exists():
                print(f"[workspace docs] subproject '{sp.name}' has "
                      f"{withheld} - removing its aggregated Doxygen output")
                sp_site = stale_dox.parent
                withdrawn = remove_tree_or_warn(
                    stale_dox, label="withdrawn aggregated Doxygen output",
                )
                if withdrawn and not any(sp_site.iterdir()):
                    # Doxygen was the only tier ever aggregated here. An empty
                    # _site/<sp>/ would still answer at its URL with a bare
                    # directory listing. A later copy this run (TypeDoc)
                    # recreates the directory it needs.
                    emptied = remove_tree_or_warn(
                        sp_site, label="empty aggregated subproject directory",
                    )
                    _dbg("OCT-DOCS", func,
                         f"sp={sp.name} empty {sp_site} removed={emptied}", 3)
            _dbg("OCT-DOCS", func, f"sp={sp.name} doxygen aggregation skipped ({withheld})", 3)
        elif mode in ("doxygen", "all"):
            _copytree_replace(
                sp.path / _DOXYGEN_BUILD_REL,
                site_root / sp.name / "doxygen" / "html",
            )
        if mode in ("typedoc", "all"):
            from oct.docs.typedoc import has_typedoc, typedoc_output_dir
            if has_typedoc(sp.path):
                _copytree_replace(
                    typedoc_output_dir(sp.path),
                    site_root / sp.name / "typedoc" / "html",
                )
 
    # Workspace-tier Option C Sphinx output (Phase D).
    if mode in ("sphinx", "all"):
        _copytree_replace(
            ws_root / "docs" / "_build" / "option_c" / "html",
            site_root / "option_c" / "sphinx" / "html",
        )
    return site_root
 
 
def _clean_workspace(
    ws_root: Path,
    workspace: Workspace,
    *,
    dry_run: bool,
) -> int:
    """Remove ``_site/`` and every subproject's ``docs/_build/`` + ``docs/html/``.
 
    Returns 0 when every target is gone (or under *dry_run*), 1 when one or
    more survived. Still best-effort in that one unremovable target never stops
    the sweep - but a survivor is reported rather than counted as removed.
    """
    func = "_clean_workspace"
    action = "Would remove" if dry_run else "Removed"
    targets: list[Path] = [ws_root / SITE_DIRNAME]
    for sp in workspace.subprojects:
        targets.extend([
            sp.path / "docs" / "html",
            sp.path / "docs" / "_build",
            sp.path / "docs" / "doxygen_output",
            sp.path / "docs" / "typedoc",
        ])
    # Workspace tier scratch (Phase D) - sweep too.
    targets.append(ws_root / "docs" / "_build")
 
    removed = 0
    survived: list[Path] = []
    for target in targets:
        if not target.exists():
            continue
        # Remove first, announce second. Announcing first (as this did) reports
        # a read-only tree as removed while it is still on disk.
        if not dry_run:
            if target.is_dir():
                if not remove_tree_or_warn(target, label="generated docs output"):
                    survived.append(target)
                    continue
            else:
                try:
                    target.unlink()
                except OSError as exc:
                    print(f"  could not remove {target}: {exc.strerror or exc}")
                    survived.append(target)
                    continue
        _dbg("OCT-DOCS", func, f"{action}: {target}", 3)
        print(f"  {action}: {target}")
        removed += 1
 
    if removed == 0 and not survived:
        print("Nothing to clean.")
    if survived:
        print(f"  {len(survived)} target(s) could not be removed (warned above).")
        return 1
    return 0
 
 
def run_workspace_docs(
    ws_root: Path,
    *,
    mode: WorkspaceDocsMode,
    dry_run: bool = False,
) -> int:
    """Workspace-mode entry point.
 
    Parameters
    ----------
    ws_root:
        Resolved path to the workspace root. The caller (dispatcher)
        guarantees this is a real workspace root.
    mode:
        Which subset of the pipeline to run. ``"sphinx"`` / ``"doxygen"``
        / ``"all"`` build subprojects + Option C tier + aggregate.
        ``"clean"`` removes ``_site/`` and every subproject's docs build
        outputs.
    dry_run:
        Forwarded to ``--clean`` only. ``True`` reports planned removals
        without touching the filesystem.
 
    Returns
    -------
    int
        ``0`` on success; non-zero when any sub-build or cleanup step
        fails. Failures in one subproject do not abort the others - every
        problem is reported in a single run.
    """
    func = "run_workspace_docs"
    _dbg("OCT-DOCS", func, f"start ws_root={ws_root} mode={mode} dry_run={dry_run}", 2)
 
    try:
        workspace = load_workspace(ws_root)
    except WorkspaceError as exc:
        print(f"Error: failed to load workspace manifest: {exc}")
        _dbg("OCT-DOCS", func, f"manifest load failed: {exc}", 1)
        return 2
 
    if mode == "clean":
        return _clean_workspace(ws_root, workspace, dry_run=dry_run)
 
    # 1. Per-subproject builds - each in-place under <sp>/docs/.
    overall_rc = 0
    for sp in workspace.subprojects:
        if not sp.html_docs:
            print(f"[workspace docs] subproject '{sp.name}' "
                  f"html_docs=false - skipping")
            _dbg("OCT-DOCS", func, f"sp={sp.name} skipped (html_docs=false)", 3)
            continue
        sp_rc = _build_subproject(sp, mode=mode)
        if sp_rc != 0:
            overall_rc = overall_rc or sp_rc
 
    # 2. Workspace-tier "Option C" Sphinx build (Phase D - wired here as
    #    a no-op stub. Phase D fills in the real implementation.)
    if mode in ("sphinx", "all"):
        try:
            from oct.docs.option_c_tier import build_option_c_tier
            tier_rc = build_option_c_tier(ws_root)
            if tier_rc != 0:
                overall_rc = overall_rc or tier_rc
        except ImportError:
            _dbg("OCT-DOCS", func, "option_c_tier module not present yet (Phase D pending)", 3)
 
    # 3. Aggregate into _site/
    site_root = _aggregate(ws_root, workspace, mode=mode)
 
    # 4. Render front page. Any mode that changes what the cards point at
    #    re-renders it, so a --typedoc or --doxygen run never leaves the hub
    #    describing the previous build.
    if mode in ("sphinx", "doxygen", "typedoc", "all"):
        from oct.docs.front_page import render_front_page, FrontPageError
        try:
            render_front_page(ws_root, site_root, workspace)
        except FrontPageError as exc:
            print(f"Warning: front page not rendered: {exc}")
            _dbg("OCT-DOCS", func, f"front page failed: {exc}", 1)
            overall_rc = overall_rc or 1
 
    print(f"\nWorkspace docs build {'failed' if overall_rc else 'complete'} -> {site_root}")
    _dbg("OCT-DOCS", func, f"end rc={overall_rc}", 2)
    return overall_rc
 
 
__all__ = [
    "WorkspaceDocsMode",
    "SITE_DIRNAME",
    "is_workspace_root",
    "run_workspace_docs",
]