option_c_tier.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/docs/option_c_tier.py
 
"""
Purpose
-------
Build the workspace-tier "Option C" Sphinx tree from the workspace's
``README.md`` (as the toctree root) and ``docs/option_c_specs/*.md``
(spec / philosophy files rendered via myst-parser). This is the third
tier in the workspace docs hub - alongside per-subproject Sphinx and
Doxygen builds - and corresponds to the front-page card linking to
``option_c/sphinx/html/``.
 
The build runs against a generated source directory under
``<workspace>/docs/_build/option_c_src/`` so the workspace's own
``docs/`` directory is never modified. Output lands under
``<workspace>/docs/_build/option_c/html/`` and is later copied into
``_site/option_c/sphinx/html/`` by
:func:`oct.docs.workspace_docs._aggregate`.
 
Responsibilities
----------------
- Generate a minimal Sphinx source tree on disk that pulls in the
  workspace ``README.md`` plus the V3.4 spec markdown files.
- Configure Sphinx with ``myst-parser`` and the project's preferred
  theme (matching subproject conf for visual consistency).
- Run ``sphinx-build`` and report the result.
- Be a no-op when the workspace has no ``docs/option_c_specs/``
  directory (so workspaces that don't ship a spec aren't forced to).
 
Diagnostics
-----------
Domain: OCT-DOCS
Levels:
    L2 - build entry / exit
    L3 - source generation steps, Sphinx invocation
    L4 - per-file decisions
 
Contracts
---------
- Generated source tree at ``docs/_build/option_c_src/`` is treated as
  ephemeral - fully regenerated on every build, never committed.
- Output HTML goes under ``docs/_build/option_c/html/``; the orchestrator
  is responsible for copying that into ``_site/option_c/sphinx/html/``.
- Sphinx invocation is a subprocess so plugin failures don't take down
  the parent ``oct docs`` process.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.tools.fs_remove (remove_tree_or_warn - clears the scratch and output trees, warning when one will not go)
"""
 
from __future__ import annotations
 
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
 
 
_SPEC_DIR_REL: Path = Path("docs") / "option_c_specs"
_SCRATCH_REL: Path = Path("docs") / "_build" / "option_c_src"
_OUTPUT_REL: Path = Path("docs") / "_build" / "option_c"
 
 
# OCT-LINT: disable=no_hardcoded_secrets reason="Sphinx conf.py template - project/author/copyright/theme settings and an extension list, no credential material (operator-ruled 2026-09-25)"
_CONF_PY_TEMPLATE: str = '''\
# Auto-generated by oct.docs.option_c_tier - do not edit.
project = "Option C"
author = "Option C Development Team"
copyright = "2026, Option C Development Team"
extensions = ["myst_parser", "sphinxcontrib.mermaid"]
# Both halves are needed, as in oct/templates/sphinx/conf.py.template: the
# extension supplies the directive, and this line is what turns a markdown
# ```mermaid fence INTO that directive. Without it the specs' nine diagrams
# rendered as plain code blocks in this tier while the subproject tier drew
# them (found 2026-09-27).
myst_fence_as_directive = {"mermaid"}
source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
master_doc = "index"
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "sphinx_book_theme"
# Off explicitly: the theme's add_source_buttons handler fails the build (rc=2)
# when the button is on without a repository_url, and this tier has no
# repository to point at. See oct/templates/sphinx/conf.py.template.
html_theme_options = {"use_repository_button": False}
html_title = "Option C"
myst_enable_extensions = ["colon_fence", "deflist", "linkify", "tasklist"]
myst_heading_anchors = 3
suppress_warnings = ["myst.header"]
'''
 
 
def _ordered_spec_files(specs_dir: Path) -> list[Path]:
    """Return spec files in their numeric prefix order (00..05).
 
    Falls back to alphabetical if files don't follow the expected
    ``NN_*.md`` pattern.
    """
    files = sorted(specs_dir.glob("*.md"))
    return files
 
 
def _write_index_md(scratch: Path, readme_text: str | None, spec_stems: list[str]) -> None:
    """Write the synthetic ``index.md`` at the root of the scratch tree.
 
    The README content is included verbatim at the top (so the tier's
    home page introduces Option C in the user's own words). Below it,
    a Sphinx ``{toctree}`` directive lists the spec files.
    """
    parts: list[str] = []
    if readme_text is not None:
        parts.append(readme_text.rstrip())
        parts.append("")
    parts.append("```{toctree}")
    parts.append(":maxdepth: 2")
    parts.append(":caption: Specification")
    parts.append("")
    for stem in spec_stems:
        parts.append(f"option_c_specs/{stem}")
    parts.append("```")
    parts.append("")
 
    (scratch / "index.md").write_text("\n".join(parts), encoding="utf-8")
 
 
def _populate_scratch(ws_root: Path, scratch: Path) -> tuple[bool, list[str]]:
    """Copy spec files + write conf.py and index.md into *scratch*.
 
    Returns ``(has_specs, spec_stems)``. ``has_specs`` is False when no
    spec files were found (caller should skip the build).
    """
    func = "_populate_scratch"
    specs_src = ws_root / _SPEC_DIR_REL
    if not specs_src.is_dir():
        _dbg("OCT-DOCS", func, f"no specs dir at {specs_src}; skipping tier build", 3)
        return False, []
 
    # A scratch dir that will not clear must not crash the following mkdir
    # (ENV-03 read-only attribute). Build over it instead: conf.py, index.md and
    # the spec copies are all rewritten, so what survives is at worst a stray
    # file Sphinx warns about being outside the toctree.
    if scratch.exists() and not remove_tree_or_warn(
            scratch, label="workspace-tier scratch"):
        print("[option_c tier] building over the scratch dir that would not "
              "clear; stale files there may add Sphinx warnings")
    scratch.mkdir(parents=True, exist_ok=True)
 
    specs_dest = scratch / "option_c_specs"
    specs_dest.mkdir(exist_ok=True)
    spec_stems: list[str] = []
    for src in _ordered_spec_files(specs_src):
        dest = specs_dest / src.name
        shutil.copy2(src, dest)
        spec_stems.append(src.stem)
        _dbg("OCT-DOCS", func, f"copied spec {src.name}", 4)
 
    if not spec_stems:
        _dbg("OCT-DOCS", func, "specs dir is empty; skipping tier build", 3)
        return False, []
 
    readme = ws_root / "README.md"
    readme_text = readme.read_text(encoding="utf-8") if readme.is_file() else None
    if readme_text is None:
        _dbg("OCT-DOCS", func, "no workspace README.md; tier index will be toctree-only", 3)
    _write_index_md(scratch, readme_text, spec_stems)
    (scratch / "conf.py").write_text(_CONF_PY_TEMPLATE, encoding="utf-8")
    return True, spec_stems
 
 
def build_option_c_tier(ws_root: Path) -> int:
    """Build the workspace-tier Sphinx HTML.
 
    Returns
    -------
    int
        ``0`` on success or when the tier is skipped (no specs); non-zero
        on Sphinx failure.
    """
    func = "build_option_c_tier"
    _dbg("OCT-DOCS", func, f"start ws_root={ws_root}", 2)
 
    scratch = ws_root / _SCRATCH_REL
    output = ws_root / _OUTPUT_REL
 
    has_specs, _ = _populate_scratch(ws_root, scratch)
    if not has_specs:
        print("[option_c tier] no docs/option_c_specs/ - skipping workspace-tier build")
        _dbg("OCT-DOCS", func, "no specs; skip", 2)
        return 0
 
    if output.exists() and not remove_tree_or_warn(
            output, label="workspace-tier HTML output"):
        print("[option_c tier] building over the previous output; pages Sphinx "
              "no longer generates may survive there")
    output.mkdir(parents=True, exist_ok=True)
 
    cmd = [
        sys.executable, "-m", "sphinx",
        "-M", "html",
        str(scratch.resolve()),  # source dir
        str(output.resolve()),   # build dir (puts html/ under it)
        "-c", str(scratch.resolve()),  # conf.py location
    ]
    print(f"[option_c tier] running: {' '.join(cmd[3:])}")
    _dbg("OCT-DOCS", func, f"sphinx-build cmd={cmd}", 3)
    try:
        result = subprocess.run(cmd, cwd=str(scratch))
    except FileNotFoundError:
        print("Error: sphinx-build not found; install with: pip install -e .[docs]")
        _dbg("OCT-DOCS", func, "sphinx-build missing", 1)
        return 1
 
    if result.returncode == 0:
        html_index = output / "html" / "index.html"
        print(f"[option_c tier] build complete -> {html_index}")
    else:
        print(f"[option_c tier] sphinx-build failed (rc={result.returncode})")
 
    _dbg("OCT-DOCS", func, f"end rc={result.returncode}", 2)
    return result.returncode
 
 
__all__ = [
    "build_option_c_tier",
]