# Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
# SPDX-License-Identifier: AGPL-3.0-or-later
"""Sphinx configuration for the DeterministicESPAsyncWebServer docs site.

Sphinx sits on top of Doxygen: `docs/Doxyfile` emits XML into `docs/sphinx/xml`, Breathe renders that
into the API reference, and MyST pulls in the hand-written Markdown guides - so the guides and the API
live in one site. The look is "squirty": the Furo theme carrying the project's Retro TTY Green Screen
brand palette and the Squirty mascot as the logo.

Build (the RPi host has doxygen + graphviz; install the Python deps into a venv):

    pip install -r docs/sphinx/requirements.txt
    doxygen docs/Doxyfile                 # regenerate docs/sphinx/xml
    sphinx-build -b html docs/sphinx docs/sphinx/_build/html
"""

import os

HERE = os.path.dirname(os.path.abspath(__file__))

project = "DeterministicESPAsyncWebServer"
copyright = "2026, Douglas Quigg (dstroy0)"
author = "Douglas Quigg (dstroy0)"

extensions = ["breathe", "myst_parser"]

# Breathe: consume the Doxygen XML (generated by docs/Doxyfile -> docs/sphinx/xml).
breathe_projects = {"DeterministicESPAsyncWebServer": os.path.join(HERE, "xml")}
breathe_default_project = "DeterministicESPAsyncWebServer"

# MyST: render the Markdown guides; enable the include/colon-fence extensions the stub pages use.
myst_enable_extensions = ["colon_fence", "deflist", "linkify"]
myst_heading_anchors = 3
source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
root_doc = "index"

exclude_patterns = ["xml", "_build", "Thumbs.db", ".DS_Store"]
# The included guides use Doxygen @ref link syntax Sphinx does not resolve; do not fail the build on them.
suppress_warnings = ["myst.xref_missing", "myst.header"]
nitpicky = False

# --- "squirty" styling: Furo + the Retro TTY Green Screen brand + the Squirty mascot ---------------
html_theme = "furo"
html_static_path = ["_static"]
html_css_files = ["squirty.css"]
html_title = "DeterministicESPAsyncWebServer"
html_logo = "../squirty.svg"
html_favicon = "../squirty.svg"

# The brand palette (docs/custom.css): green #2bb35a phosphor on a near-black #080c08 CRT.
_green = "#2bb35a"
_green_light = "#40ff40"
_green_dark = "#008000"
_bg = "#080c08"
_code_bg = "#001100"
html_theme_options = {
    "light_css_variables": {
        "color-brand-primary": _green_dark,
        "color-brand-content": _green_dark,
        "font-stack--monospace": "'JetBrains Mono', 'Fira Code', ui-monospace, monospace",
    },
    "dark_css_variables": {
        "color-brand-primary": _green,
        "color-brand-content": _green_light,
        "color-background-primary": _bg,
        "color-background-secondary": "#0b0f0b",
        "color-foreground-primary": _green,
        "color-code-background": _code_bg,
        "color-code-foreground": _green,
        "font-stack--monospace": "'JetBrains Mono', 'Fira Code', ui-monospace, monospace",
    },
}
