conf.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# docs/_sphinx/conf.py
 
"""
Purpose
-------
Sphinx configuration for the OCT project documentation build.
 
Responsibilities
----------------
- Define project metadata (name, version, author, copyright).
- Register Sphinx extensions (MyST, Mermaid, autodoc, Napoleon, etc.).
- Configure HTML theme, static paths, and template paths.
 
Diagnostics
-----------
Domain: DOCS
L2: documentation build configuration
L3: build configuration details
L4: deep tracing
 
Contracts
---------
- This file is consumed by ``sphinx-build`` and ``oct docs --sphinx``.
- Paths in ``templates_path`` and ``html_static_path`` are relative to
  the confdir (``docs/_sphinx/``).
"""
# OCT-LINT: disable-file=dbg_import reason="Sphinx executes conf.py itself; it is build configuration, not an Option C module, and must not import the project runtime (operator-ruled 2026-09-27, same form as secret_scanner.py)"
# OCT-LINT: disable-file=dbg_usage reason="Sphinx executes conf.py itself; it is build configuration, not an Option C module (operator-ruled 2026-09-27)"
 
# Configuration file for the Sphinx documentation builder.
#
# Generated by: oct docs --sphinx / oct scaffold
# Lives in: docs/_sphinx/conf.py
 
import os
import sys
 
# Allow autodoc to import project modules
# Path: _sphinx/ → docs/ → project_root/
sys.path.insert(0, os.path.abspath('../..'))
 
# -- Project information -----------------------------------------------------
 
project = 'oct'
copyright = '2026, Option C Dev Team'
author = 'Option C Dev Team'
release = '0.9.1'
 
# -- General configuration ---------------------------------------------------
 
extensions = [
    'myst_parser',
    'sphinxcontrib.mermaid',
    'sphinx.ext.autosectionlabel',
    'sphinx_copybutton',
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.viewcode',
    'sphinx.ext.inheritance_diagram',
    'sphinx.ext.napoleon',
]
 
# Prefix section labels with document name to avoid duplicates across modules
autosectionlabel_prefix_document = True
 
myst_enable_extensions = [
    'colon_fence',
    'attrs_inline',
    'smartquotes',
    'replacements',
]
 
myst_heading_anchors = 3
 
# Convert ```mermaid fenced blocks to Sphinx mermaid directives
myst_fence_as_directive = {"mermaid"}
 
# templates_path and html_static_path are relative to confdir (docs/_sphinx/)
templates_path = ['../_templates']
exclude_patterns = ['html', 'doctrees', 'old', 'code_reviews', 'sphinx_docs',
                    'source', '_sphinx', '_templates', '_autosummary',
                    'doxygen_output', 'doxygen_work_dir',
                    'Thumbs.db', '.DS_Store']
 
# Suppress noisy warnings from markdown files
suppress_warnings = ['myst.xref_missing', 'myst.header', 'docutils',
                     'autosectionlabel.*']
 
# -- Autodoc configuration --------------------------------------------------
 
autosummary_generate = True
 
autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'show-inheritance': True,
    # Document each re-exported name once, where it is defined; otherwise an
    # unqualified reference has two targets (operator-ruled 2026-09-27).
    'ignore-module-all': True,
}
 
# Option C docstrings carry a numpy-style "Attributes" section. Napoleon's
# default turns it into `.. attribute::` directives, which are index
# entries; autodoc's undoc-members then documents the same dataclass field
# again ("duplicate object description ... use :no-index:"). Rendering the
# section as :ivar: fields leaves autodoc's entry as the only indexed one.
# (operator-ruled 2026-09-27)
napoleon_use_ivar = True
 
# -- Options for HTML output -------------------------------------------------
 
html_theme = 'sphinx_book_theme'
html_static_path = ['../_static']
html_css_files = ['custom.css']
html_logo = '../_static/Option_C_logo.svg'
 
html_theme_options = {
    "repository_url": "https://github.com/available/soon",
    "use_repository_button": True,
    "use_fullscreen_button": True,
    "use_download_button": True,
    "home_page_in_toc": True,
    "show_toc_level": 2,
}