{"id":9325,"library":"sphinxcontrib-googleanalytics","title":"Sphinx Google Analytics Extension","description":"sphinxcontrib-googleanalytics is a Sphinx extension that enables tracking of generated HTML documentation files using the Google Analytics web service. The current version is 0.5, and it maintains an infrequent release cadence, with the latest release 0.5 published approximately 11 months ago and 0.4 released in January 2023.","status":"active","version":"0.5","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/googleanalytics","tags":["sphinx","extension","google analytics","documentation","analytics"],"install":[{"cmd":"pip install sphinxcontrib-googleanalytics","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to function. Specific Python version requirements are inherited from the Sphinx version in use.","package":"Sphinx","optional":false}],"imports":[{"note":"This is a Sphinx extension and is enabled by adding its module name to the 'extensions' list in Sphinx's conf.py, not by a direct Python import statement for runtime use.","wrong":"import sphinxcontrib.googleanalytics","symbol":"sphinxcontrib.googleanalytics","correct":"# In conf.py, add to extensions list:\nextensions = ['sphinxcontrib.googleanalytics']"}],"quickstart":{"code":"import os\n\n# conf.py example\n\nproject = 'My Project'\ncopyright = '2026, My Team'\nauthor = 'My Team'\nrelease = '0.1'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    # Enable the Google Analytics extension\n]\n\n# Only enable Google Analytics if an ID is provided, useful for CI/CD environments\ngoogleanalytics_id = os.environ.get('GOOGLE_ANALYTICS_ID', '')\nif googleanalytics_id:\n    extensions.append('sphinxcontrib.googleanalytics')\n    # Optionally enable/disable tracking based on environment variable\n    # googleanalytics_enabled = os.environ.get('GOOGLE_ANALYTICS_ENABLED', 'True').lower() == 'true'","lang":"python","description":"To quickly integrate sphinxcontrib-googleanalytics, add `sphinxcontrib.googleanalytics` to your `extensions` list in `conf.py` and set the `googleanalytics_id` variable to your Google Analytics Tracking ID (e.g., `G-XXXXXXXXX` for GA4 or `UA-XXXXXXXXX` for Universal Analytics). It's common to conditionally enable this based on an environment variable for local builds vs. production deployments, preventing local tracking."},"warnings":[{"fix":"Remove `analytics_id` and `analytics_anonymize_ip` from `html_theme_options` in `conf.py`. Instead, add `sphinxcontrib.googleanalytics` to your `extensions` list and set `googleanalytics_id` directly in `conf.py`.","message":"The `analytics_id` and `analytics_anonymize_ip` options in the `Read the Docs Sphinx Theme` are deprecated. Users of this theme should switch to using `sphinxcontrib-googleanalytics` for Google Analytics integration.","severity":"deprecated","affected_versions":"sphinx_rtd_theme >= 3.0.0"},{"fix":"Consult legal advice regarding GDPR compliance for your specific use case. Consider alternative, privacy-focused analytics solutions if GDPR compliance is a strict requirement without custom implementation.","message":"Google Analytics (and thus this extension) may not inherently be compliant with GDPR without additional infrastructure to manage user consent.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify your Google Analytics property type and use the corresponding tracking ID format in your `conf.py` file.","message":"Ensure you use the correct Google Analytics ID format for your property: `G-XXXXXXXXX` for Google Analytics 4 (GA4) or `UA-XXXXXXXXX` for Universal Analytics.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your Sphinx installation is up-to-date and compatible with the `sphinxcontrib-googleanalytics` version. Consider creating a fresh virtual environment to isolate dependencies. Check GitHub issues for specific Sphinx version compatibility.","cause":"This error typically indicates an incompatibility issue, possibly with an older or conflicting version of Sphinx or related dependencies.","error":"Extension error: Could not import extension sphinxcontrib.googleanalytics (exception: cannot import name 'ExtensionError')"},{"fix":"Remove `analytics_id` from `html_theme_options`. Instead, add `sphinxcontrib.googleanalytics` to your `extensions` list in `conf.py` and set `googleanalytics_id = 'YOUR_GA_ID'` at the top level of your `conf.py`.","cause":"If you are using a Sphinx theme like `sphinx_rtd_theme`, the `analytics_id` option within `html_theme_options` has been deprecated in favor of using the `sphinxcontrib-googleanalytics` extension directly.","error":"Google Analytics tracking is not working, but I have set `analytics_id` in `html_theme_options`."},{"fix":"Ensure the `googleanalytics_id` variable is explicitly set in your `conf.py` or configured via an environment variable that is properly exposed in your CI/CD pipeline. Use `os.environ.get('GOOGLE_ANALYTICS_ID', '')` to retrieve the ID, and conditionally append `sphinxcontrib.googleanalytics` to `extensions` only if the ID is present, as shown in the quickstart.","cause":"The `googleanalytics_id` might not be set or correctly passed to the build environment during CI/CD, or the extension might be conditionally enabled.","error":"Google Analytics tracking works locally but not in my CI/CD (e.g., GitHub Actions, Read the Docs) build."}]}