Merge pull request #527 from vcs-python/fix/theme-flicker-conf

tony · web-flow · commit 580908ed708b · 2026-05-03T18:09:02.000-05:00
fix(docs): restore gp-sphinx FOWT prevention
diff --git a/CHANGES b/CHANGES
@@ -20,6 +20,15 @@ $ uv add libvcs --prerelease allow
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Bug fixes
+
+- Fix dark-theme flash when light theme is selected — the docs
+  `conf.py` was overriding gp-sphinx's `setup()` callback, so the
+  inline FOWT-prevention `<script>` never landed in `<head>`. Chain
+  the gp-sphinx setup explicitly so the script (and the
+  `spa-nav.js` / copybutton / MyST-lexer hooks) register correctly
+  (#527)
+
 ### Documentation
 
 - Bump gp-sphinx docs stack to v0.0.1a16 — docs site now renders
diff --git a/docs/conf.py b/docs/conf.py
@@ -62,6 +62,8 @@
     html_extra_path=["manifest.json"],
     rediraffe_redirects="redirects.txt",
 )
+
+_gp_setup = conf.pop("setup")
 globals().update(conf)
 
 
@@ -91,5 +93,14 @@ def _on_missing_class_reference(
 
 
 def setup(app: Sphinx) -> None:
-    """Connect missing-reference handler to resolve py:data as :class: links."""
+    """Chain gp-sphinx setup() and connect the missing-reference handler.
+
+    ``_gp_setup`` is the callback ``gp_sphinx.config.merge_sphinx_config``
+    returns; it registers the FOWT-prevention head injection,
+    ``spa-nav.js``, the copy-button bridge, the ``remove_tabs_js``
+    cleanup, and the MyST Pygments lexers. Without this chain those
+    hooks never register and the docs site flashes the wrong theme
+    before settling on the user's preference.
+    """
+    _gp_setup(app)
     app.connect("missing-reference", _on_missing_class_reference)
