oct.docs.option_c_tier Namespace Reference

Functions
list[Path]	_ordered_spec_files (Path specs_dir)
None	_write_index_md (Path scratch, str|None readme_text, list[str] spec_stems)
tuple[bool, list[str]]	_populate_scratch (Path ws_root, Path scratch)
int	build_option_c_tier (Path ws_root)

Variables
Path	_SPEC_DIR_REL = Path("docs") / "option_c_specs"
Path	_SCRATCH_REL = Path("docs") / "_build" / "option_c_src"
Path	_OUTPUT_REL = Path("docs") / "_build" / "option_c"
str	_CONF_PY_TEMPLATE

Detailed Description

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)

Function Documentation

_ordered_spec_files()

list[Path] oct.docs.option_c_tier._ordered_spec_files ( Path specs_dir )

protected

Return spec files in their numeric prefix order (00..05).

Falls back to alphabetical if files don't follow the expected
``NN_*.md`` pattern.

Definition at line 99 of file option_c_tier.py.

Here is the caller graph for this function:

_populate_scratch()

tuple[bool, list[str]] oct.docs.option_c_tier._populate_scratch ( Path ws_root, Path scratch )

protected

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).

Definition at line 132 of file option_c_tier.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_write_index_md()

None oct.docs.option_c_tier._write_index_md ( Path scratch, str | None readme_text, list[str] spec_stems )

protected

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.

Definition at line 109 of file option_c_tier.py.

Here is the caller graph for this function:

build_option_c_tier()

int oct.docs.option_c_tier.build_option_c_tier

(

Path

ws_root

)

Build the workspace-tier Sphinx HTML.

Returns
-------
int
    ``0`` on success or when the tier is skipped (no specs); non-zero
    on Sphinx failure.

Definition at line 176 of file option_c_tier.py.

Here is the call graph for this function:

Variable Documentation

_CONF_PY_TEMPLATE

str oct.docs.option_c_tier._CONF_PY_TEMPLATE

protected

Initial value:

=  '''\
# 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"]
'''

Definition at line 72 of file option_c_tier.py.

_OUTPUT_REL

Path oct.docs.option_c_tier._OUTPUT_REL = Path("docs") / "_build" / "option_c"

protected

Definition at line 68 of file option_c_tier.py.

_SCRATCH_REL

Path oct.docs.option_c_tier._SCRATCH_REL = Path("docs") / "_build" / "option_c_src"

protected

Definition at line 67 of file option_c_tier.py.

_SPEC_DIR_REL

Path oct.docs.option_c_tier._SPEC_DIR_REL = Path("docs") / "option_c_specs"

protected

Definition at line 66 of file option_c_tier.py.