feat: monkey-patch HTML builder

docs/conf.py

@@ -13,6 +13,9 @@
 
 load_dotenv()
 
+pygments_style = "solarized-light"
+pygments_style_dark = "github-dark"
+
 # -- Project information ---
 
 project = "Awesome Sphinx Theme"

docs/readthedocs.txt

@@ -30,7 +30,7 @@ sphinx-autobuild==2021.3.14 ; python_version >= "3.8" and python_version < "3.9"
 sphinx-autobuild==2024.4.16 ; python_version >= "3.9" and python_version < "3.13"
 sphinx-design==0.5.0 ; python_version >= "3.8" and python_version < "3.9"
 sphinx-design==0.6.0 ; python_version >= "3.9" and python_version < "3.13"
-sphinx-docsearch==0.0.6 ; python_version >= "3.8" and python_version < "4.0"
+sphinx-docsearch==0.0.7 ; python_version >= "3.8" and python_version < "4.0"
 sphinx-sitemap==2.6.0 ; python_version >= "3.8" and python_version < "4.0"
 sphinx==7.1.2 ; python_version >= "3.8" and python_version < "3.9"
 sphinx==7.3.7 ; python_version >= "3.9" and python_version < "4.0"

pyproject.toml

@@ -38,7 +38,7 @@ sphinx-design = [
   { version = "^0.5.0", python = ">=3.8,<3.9" },
   { version = "^0.6.0", python = ">=3.9,<3.13" },
 ]
-sphinx-docsearch = "^0.0.6"
+sphinx-docsearch = "^0.0.7"
 python-dotenv = ">=0.19,<1.1"
 
 [tool.poetry.group.dev.dependencies]
@@ -53,7 +53,7 @@ pre-commit = [
   { version = "^3.5", python = ">=3.8,<3.9"},
   { version = "^3.6", python = ">=3.9,<3.13"},
 ]
-ruff = ">=0.0.269,<0.4.6"
+ruff = ">=0.0.269,<0.4.7"
 
 [tool.poetry.group.netlify.dependencies]
 nox = {version = ">=2023.4.22,<2025.0.0", python = "3.8"}

src/sphinxawesome_theme/__init__.py

@@ -12,10 +12,11 @@
 from typing import Any, TypedDict
 
 from sphinx.application import Sphinx
+from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.util import logging
 from sphinxcontrib.serializinghtml import JSONHTMLBuilder
 
-from . import jinja_functions, jsonimpl, logos, postprocess, toc
+from . import builder, jinja_functions, jsonimpl, logos, postprocess, toc
 
 logger = logging.getLogger(__name__)
 
@@ -165,6 +166,13 @@ def setup(app: Sphinx) -> dict[str, Any]:
     """Register the theme and its extensions wih Sphinx."""
     here = Path(__file__).parent.resolve()
 
+    app.add_config_value("pygments_style_dark", None, "html", str)
+    # Monkey-patch galore
+    StandaloneHTMLBuilder.init_highlighter = builder.AwesomeHTMLBuilder.init_highlighter  # type: ignore
+    StandaloneHTMLBuilder.create_pygments_style_file = (  # type: ignore
+        builder.AwesomeHTMLBuilder.create_pygments_style_file  # type: ignore
+    )
+
     app.add_html_theme(name="sphinxawesome_theme", theme_path=str(here))
     app.add_js_file("theme.js", loading_method="defer")
 

src/sphinxawesome_theme/builder.py

@@ -0,0 +1,61 @@
+"""Override code from the default HTML builder related to pygments CSS.
+
+This extension extends the default HTML builder by changing the way
+Pygments CSS is handled.
+
+- Add a ``pygments_style_dark`` configuration option.
+- Append dark mode classes to the main ``pygments.css`` file,
+  instead of writing them in a separate file,
+  properly prepend all classes for dark mode with `.dark`
+
+:copyright: Copyright Kai Welke.
+:license: MIT, see LICENSE for details.
+"""
+
+from __future__ import annotations
+
+from os import path
+
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.highlighting import PygmentsBridge
+
+
+class AwesomeHTMLBuilder(StandaloneHTMLBuilder):
+    """HTML builder that overrides a few methods related to handling CSS for Pygments."""
+
+    def init_highlighter(self: AwesomeHTMLBuilder) -> None:
+        """Initialize Pygments highlighters."""
+        # ``pygments_style`` from config
+        if self.config.pygments_style is not None:
+            style = self.config.pygments_style
+        elif self.theme:
+            # From the ``pygments_style`` theme setting
+            style = self.theme.pygments_style_default or "none"
+        else:
+            style = "sphinx"
+
+        self.highlighter = PygmentsBridge("html", style)
+
+        if self.config.pygments_style_dark is not None:
+            dark_style = self.config.pygments_style_dark
+        elif self.theme:
+            dark_style = self.theme.pygments_style_dark
+        else:
+            dark_style = None
+
+        self.dark_highlighter: PygmentsBridge | None
+        if dark_style is not None:
+            self.dark_highlighter = PygmentsBridge("html", dark_style)
+        else:
+            self.dark_highlighter = None
+
+    def create_pygments_style_file(self: AwesomeHTMLBuilder) -> None:
+        """Create CSS file for Pygments."""
+        stylesheet = self.highlighter.get_stylesheet()
+        if self.dark_highlighter:
+            stylesheet += self.dark_highlighter.get_stylesheet(arg=".dark")  # type: ignore
+
+        with open(
+            path.join(self.outdir, "_static", "pygments.css"), "w", encoding="utf-8"
+        ) as f:
+            f.write(stylesheet)