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/``).
"""
 
# 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,
}
 
# -- 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,
}