russell@unturf.com
546fa6d690
Adds a Sphinx extension at docs/_source/_ext/makefile_targets.py that parses the project Makefile's '## description' annotations and writes docs/_source/api/makefile.rst at build time. Same convention 'make help' uses, so the reference stays in sync with the source. Generated page is grouped by target prefix (fetch-, ingest-, distill-, docs-, etc.) and rendered as a list-table. Shows on RTD alongside the autodoc API modules. Generated file is gitignored — RTD regenerates on every build.
48 lines
1.2 KiB
Python
48 lines
1.2 KiB
Python
"""Sphinx configuration for Aborist API reference."""
|
|
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
# Add aborist package + local _ext (Sphinx extensions) to path
|
|
project_root = Path(__file__).parent.parent.parent
|
|
sys.path.insert(0, str(project_root))
|
|
sys.path.insert(0, str(Path(__file__).parent / "_ext"))
|
|
|
|
# Project info
|
|
project = "Aborist"
|
|
copyright = "2026, agent blackops"
|
|
author = "fox/timehexon"
|
|
version = "9.8"
|
|
release = "9.8.0"
|
|
|
|
# Extensions
|
|
extensions = [
|
|
"sphinx.ext.autodoc",
|
|
"sphinx.ext.napoleon",
|
|
"sphinx.ext.intersphinx",
|
|
"sphinx.ext.viewcode",
|
|
"makefile_targets", # local: generates api/makefile.rst from Makefile ## annotations
|
|
]
|
|
|
|
# Autodoc settings
|
|
autodoc_member_order = "bysource"
|
|
autodoc_typehints = "description"
|
|
autodoc_typehints_format = "short"
|
|
|
|
# Napoleon (Google/NumPy docstring) settings
|
|
napoleon_google_docstring = False
|
|
napoleon_numpy_docstring = True
|
|
napoleon_attr_annotations = True
|
|
|
|
# HTML output
|
|
html_theme = "furo"
|
|
html_static_path = ["_static"]
|
|
html_title = "Aborist API Reference"
|
|
|
|
# Suppress warnings for missing references
|
|
suppress_warnings = ["ref.doc"]
|
|
|
|
# Intersphinx mapping (for external doc links)
|
|
intersphinx_mapping = {
|
|
"python": ("https://docs.python.org/3", None),
|
|
}
|