oct.docs.oct_docs module

oct.docs.oct_docs module#

Purpose#

Provide documentation generation pipelines for Option C projects: oct docs --sphinx, oct docs --doxygen, oct docs --all, and oct docs --clean.

Responsibilities#

  • Set up Sphinx configuration in the project’s docs/ directory (if not already present).

  • Discover markdown documentation files already in docs/.

  • Generate API reference pages from Python module docstrings via autodoc.

  • Generate dependency graph pages via oct deps.

  • Populate index.rst with all discovered content.

  • Run sphinx-build to generate HTML output.

  • Check for required Sphinx dependencies and emit a clear error if missing.

  • Run Doxygen with a patched Doxyfile (correcting stale INPUT paths).

  • Clean generated documentation artifacts while preserving user-authored files.

Diagnostics#

Domain: OCT-DOCS Levels:

L2 — lifecycle L3 — semantic details L4 — deep tracing

Contracts#

  • Must not overwrite existing conf.py if already present.

  • index.rst is regenerated on every build (auto-generated content).

  • Must exit 1 with a helpful message if Sphinx dependencies are not installed.

  • Template files are bundled in oct/templates/sphinx/.

  • Doxygen runs on a temporary copy of the Doxyfile; the original is never modified.

  • --clean preserves _sphinx/, _static/, _templates/, doxygen_work_dir/, and user-authored markdown files.

Dependencies#

  • oct.deps.oct_deps (dependency graph generation)

  • oct.core.exclusions (directory exclusion lists)

oct.docs.oct_docs.run_docs_all(root: Path) → int[source]#

Run both Sphinx and Doxygen pipelines.

Returns 0 if both succeed, 1 if either fails.

oct.docs.oct_docs.run_docs_clean(root: Path, *, dry_run: bool = False) → int[source]#

Remove generated documentation artifacts from docs/.

Cleans: html/, doctrees/, _api/, doxygen_output/,

index.rst, dependencies.rst

Preserves: _sphinx/ (user conf.py), _static/, _templates/,

user-authored .md files, doxygen_work_dir/Doxyfile

Returns 0 always.

oct.docs.oct_docs.run_docs_doxygen(root: Path) → int[source]#

Full oct docs –doxygen pipeline.

  1. Check doxygen is installed (shutil.which)

  2. Find existing Doxyfile in docs/doxygen_work_dir/

  3. Create patched temp copy with correct INPUT

  4. Run doxygen on the temp Doxyfile

  5. Clean up temp Doxyfile

  6. Report output location (docs/doxygen_output/)

Returns exit code: 0 on success, 1 on failure.

oct.docs.oct_docs.run_docs_sphinx(root: Path) → int[source]#

Full oct docs –sphinx pipeline.

  1. Check dependencies

  2. Set up Sphinx config (one-time)

  3. Load .octrc.json docs configuration

  4. Discover markdown files

  5. Generate API reference (autodoc)

  6. Generate dependency graph

  7. Write populated index.rst

  8. Run sphinx-build

Returns exit code.

oct.docs.oct_docs.run_sphinx_build(docs_dir: Path, config: dict) → int[source]#

Run sphinx-build to generate HTML output.

Returns exit code: 0 on success, 1 on failure.

oct.docs.oct_docs.setup_sphinx(root: Path) → Path[source]#

Set up Sphinx configuration in the project’s docs/ directory.

Uses docs/ as the Sphinx source directory directly — markdown files already present in docs/ are included without copying.

Sphinx config files (conf.py, Makefile, make.bat) live in docs/_sphinx/ to keep the docs/ root clean. The -c flag in run_sphinx_build points Sphinx at this configuration directory.

Returns the path to the docs directory.