"""Sphinx configuration for Arborist API reference."""

import sys
from pathlib import Path

# Add arborist 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 = "Arborist"
copyright = "russell@unturf./foxhop/TimeHexOn/legallydav1dpro unturf permacomputers 2026"
author = "russell@unturf."
version = "9.8"
release = "9.8.0"

# Extensions
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
    "sphinx.ext.viewcode",
    "sphinx.ext.graphviz",  # .. graphviz:: DOT diagrams (needs `dot` on the build)
    "makefile_targets",  # local: generates api/makefile.rst from Makefile ## annotations
]

# Render DOT diagrams to SVG (crisp, themeable) rather than PNG.
graphviz_output_format = "svg"

# 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 = "sphinx_book_theme"
html_static_path = ["_static"]
html_title = "Arborist API Reference"

# Click-to-zoom lightbox for diagrams (graphviz SVG + img.zoomable).
# Vendored, dependency-free — see _static/zoom.{css,js}.
html_css_files = ["zoom.css"]
html_js_files = ["zoom.js"]

# Standard sphinx-book-theme layout: full project TOC on the left,
# 'On this page' (current page sections) on the right. show_toc_level=3
# expands the right TOC down to subsections.
html_theme_options = {
    "show_toc_level": 3,
    "show_navbar_depth": 2,
}

# Suppress warnings for missing references
suppress_warnings = ["ref.doc"]

# Per-page footer: appended to every RST source file before parsing.
# Carries the Permacomputer Preamble; full license at /license.
rst_epilog = """

----

.. rubric:: Permacomputer Preamble — License: AGPL-3.0-only

This is free software for the public good of a permacomputer hosted at
`permacomputer.com <https://www.permacomputer.com>`_, an always-on computer
by the people, for the people. Durable, easy to repair, & distributed like
tap water for machine learning intelligence.

Our permacomputer is community-owned infrastructure optimized around four
values:

* **TRUTH** — First principles, math & science, open source code freely
  distributed.
* **FREEDOM** — Voluntary partnerships, freedom from tyranny & corporate
  control.
* **HARMONY** — Minimal waste, self-renewing systems with diverse thriving
  connections.
* **LOVE** — Be yourself without hurting others, cooperation through natural
  law.

NO WARRANTY. Software is provided "AS IS" without warranty of any kind.
Full text: :doc:`/license`.
"""

# Intersphinx mapping (for external doc links)
intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}