From af2bff00f172e012dadcc4f579f11e594d174ea7 Mon Sep 17 00:00:00 2001
From: Sean Burton <sean.burton@quantinuum.com>
Date: Wed, 1 Jul 2026 16:23:36 +0100
Subject: [PATCH] feat: allow disabling of analytics through a Sphinx option

---
 sphinx-ui/demo/source/conf.py          | 7 +++++++
 sphinx-ui/quantinuum_sphinx/page.html  | 2 +-
 sphinx-ui/quantinuum_sphinx/theme.toml | 6 ++++++
 sphinx-ui/react/src/injectNav.tsx      | 4 +++-
 4 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/sphinx-ui/demo/source/conf.py b/sphinx-ui/demo/source/conf.py
index 78c9521..9794152 100644
--- a/sphinx-ui/demo/source/conf.py
+++ b/sphinx-ui/demo/source/conf.py
@@ -21,3 +21,10 @@
 
 html_theme = 'quantinuum_sphinx'
 html_static_path = ['_static']
+
+# Google Analytics is disabled by default so non-production environments
+# (e.g. staging) do not send analytics. Enable it only in the production
+# build's conf.py:
+# html_theme_options = {
+#     'enable_analytics': True,
+# }
diff --git a/sphinx-ui/quantinuum_sphinx/page.html b/sphinx-ui/quantinuum_sphinx/page.html
index 3ea525b..b50cb19 100644
--- a/sphinx-ui/quantinuum_sphinx/page.html
+++ b/sphinx-ui/quantinuum_sphinx/page.html
@@ -30,7 +30,7 @@
  <!--Force light mode -->
  <script>document.body.setAttribute('data-theme','light')</script>
 <nav style="position:fixed;top:0;z-index:1021;width:100%;">
-    <div class="nexus-nav"></div>
+    <div class="nexus-nav" data-analytics-enabled="{{ 'true' if theme_enable_analytics else 'false' }}"></div>
 </nav>
 <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
 <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
diff --git a/sphinx-ui/quantinuum_sphinx/theme.toml b/sphinx-ui/quantinuum_sphinx/theme.toml
index cac9490..9db0121 100644
--- a/sphinx-ui/quantinuum_sphinx/theme.toml
+++ b/sphinx-ui/quantinuum_sphinx/theme.toml
@@ -7,3 +7,9 @@ stylesheets = [
   "styles/quantinuum-ui-tailwind.css",
   "styles/quantinuum-sphinx.css",
 ]
+
+[options]
+# Enable Google Analytics. Disabled by default so non-production
+# environments (e.g. staging) do not send analytics. Set to true in the
+# production conf.py via html_theme_options = {"enable_analytics": True}.
+enable_analytics = false
diff --git a/sphinx-ui/react/src/injectNav.tsx b/sphinx-ui/react/src/injectNav.tsx
index 5a078e0..d0fad4a 100644
--- a/sphinx-ui/react/src/injectNav.tsx
+++ b/sphinx-ui/react/src/injectNav.tsx
@@ -94,6 +94,8 @@ const observeTailwindDialogPortalElements = () => {
   const mountElement = document.querySelector('.nexus-nav')
   if (!mountElement) return
 
+  const analyticsEnabled = mountElement.getAttribute('data-analytics-enabled') === 'true'
+
   observeTailwindDialogPortalElements()
 
   const renderIn = document.createElement('div')
@@ -106,7 +108,7 @@ const observeTailwindDialogPortalElements = () => {
       <div className="antialiased" style={{ fontFamily: `Inter, ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"` }}>
         <CookieConsentProvider version={1}>
           <CookieConditional category={CookieCategoryName.Analytics} fallback={null}>
-            {GA_ID && <GoogleAnalytics gaId={GA_ID} />}
+            {analyticsEnabled && GA_ID && <GoogleAnalytics gaId={GA_ID} />}
           </CookieConditional>
           <DocsNavBar activePath="/" />
           <CookieConsentManager />