feat: allow disabling of analytics through a Sphinx option (#43)

Author: sburton84

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,
+# }

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">

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

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 />