Add plausible analytics

docs/user_guide/analytics.rst

@@ -1,6 +1,36 @@
 Analytics and usage services
 ============================
 
+The theme supports several web analytics services via the ``analytics`` option. It is configured
+by passing a dictionary with options. See the sections bellow for relevant
+options depending on the analytics provider that you want to use.
+
+.. code:: python
+
+   html_theme_options = {
+       "analytics": analytics_options,
+   }
+
+Plausible Analytics (recommended)
+=================================
+
+https://plausible.io can be used to gather simple
+and privacy-friendly analytics for the site. The configuration consists in
+a server URL and a specific domain. Plausible' javascript will be included in
+all html pages to gather metrics. And the dashboard can be accessed at
+``https://url/my_domain``.
+
+The Scientific-Python community can offer a self-hosted server. Contact the
+team on social media following https://scientific-python.org for assistance.
+
+.. code:: python
+
+   # To be re-used in html_theme_options["analytics"]
+   analytics_options = {
+       "plausible_analytics_domain": "my-domain",
+       "plausible_analytics_url": "https://.../script.js",
+   }
+
 Google Analytics
 ================
 
@@ -9,6 +39,7 @@ Google Analytics' javascript is included in the html pages.
 
 .. code:: python
 
-   html_theme_options = {
+   # To be re-used in html_theme_options["analytics"]
+   analytics_options = {
        "google_analytics_id": "G-XXXXXXXXXX",
    }

src/pydata_sphinx_theme/__init__.py

@@ -2,6 +2,7 @@
 Bootstrap-based sphinx theme from the PyData community
 """
 import os
+import warnings
 from pathlib import Path
 
 import jinja2
@@ -49,33 +50,62 @@ def update_config(app, env):
         )
 
     # Add an analytics ID to the site if provided
-    # Currently only supports the two types of Google Analytics id.
+
+    # deprecated options for Google Analytics
+    # TODO: deprecate >= v0.12
     gid = theme_options.get("google_analytics_id")
     if gid:
-        # In this case it is "new-style" google analytics
-        if "G-" in gid:
-            gid_js_path = f"https://www.googletagmanager.com/gtag/js?id={gid}"
-            gid_script = f"""
-                window.dataLayer = window.dataLayer || [];
-                function gtag(){{ dataLayer.push(arguments); }}
-                gtag('js', new Date());
-                gtag('config', '{gid}');
-            """
-        # In this case it is "old-style" google analytics
+        msg = (
+            "'google_analytics_id' is deprecated and will be removed in "
+            "version 0.11, please refer to the documentation "
+            "and use 'analytics' instead."
+        )
+        warnings.warn(msg, DeprecationWarning, stacklevel=2)
+        if theme_options.get("analytics"):
+            theme_options["analytics"].update({"google_analytics_id": gid})
         else:
-            gid_js_path = "https://www.google-analytics.com/analytics.js"
-            gid_script = f"""
-                window.ga = window.ga || function () {{
-                    (ga.q = ga.q || []).push(arguments) }};
-                ga.l = +new Date;
-                ga('create', '{gid}', 'auto');
-                ga('set', 'anonymizeIp', true);
-                ga('send', 'pageview');
-            """
+            theme_options["analytics"] = {"google_analytics_id": gid}
 
-        # Link the JS files
-        app.add_js_file(gid_js_path, loading_method="async")
-        app.add_js_file(None, body=gid_script)
+    analytics = theme_options.get("analytics")
+    if analytics:
+        # Plausible analytics
+        plausible_domain = analytics.get("plausible_analytics_domain")
+        plausible_url = analytics.get("plausible_analytics_url")
+
+        if plausible_domain and plausible_url:
+            plausible_script = f"""
+                data-domain={plausible_domain} src={plausible_url}
+            """
+            # Link the JS file
+            app.add_js_file(None, body=plausible_script, loading_method="defer")
+
+        # Two types of Google Analytics id.
+        gid = analytics.get("google_analytics_id")
+        if gid:
+            # In this case it is "new-style" google analytics
+            if "G-" in gid:
+                gid_js_path = f"https://www.googletagmanager.com/gtag/js?id={gid}"
+                gid_script = f"""
+                    window.dataLayer = window.dataLayer || [];
+                    function gtag(){{ dataLayer.push(arguments); }}
+                    gtag('js', new Date());
+                    gtag('config', '{gid}');
+                """
+            # In this case it is "old-style" google analytics
+            else:
+                gid_js_path = "https://www.google-analytics.com/analytics.js"
+                gid_script = f"""
+                    window.ga = window.ga || function () {{
+                        (ga.q = ga.q || []).push(arguments) }};
+                    ga.l = +new Date;
+                    ga('create', '{gid}', 'auto');
+                    ga('set', 'anonymizeIp', true);
+                    ga('send', 'pageview');
+                """
+
+            # Link the JS files
+            app.add_js_file(gid_js_path, loading_method="async")
+            app.add_js_file(None, body=gid_script)
 
 
 def prepare_html_config(app, pagename, templatename, context, doctree):

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -18,6 +18,7 @@ twitter_url =
 icon_links_label = Icon Links
 icon_links =
 google_analytics_id =
+analytics =
 favicons =
 show_prev_next = True
 search_bar_text = Search the docs ...

tests/test_build.py

@@ -540,30 +540,41 @@ def test_edit_page_url(sphinx_build_factory, html_context, edit_url):
     assert edit_link[0].attrs["href"] == edit_url, f"edit link didn't match {edit_link}"
 
 
-def test_new_google_analytics_id(sphinx_build_factory):
-    confoverrides = {"html_theme_options.google_analytics_id": "G-XXXXX"}
-    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides)
-    sphinx_build.build()
-    index_html = sphinx_build.html_tree("index.html")
-
-    # Search all the scripts and make sure one of them has the Google tag in there
-    tags_found = False
-    for script in index_html.select("script"):
-        if script.string and "gtag" in script.string and "G-XXXXX" in script.string:
-            tags_found = True
-    assert tags_found is True
-
-
-def test_old_google_analytics_id(sphinx_build_factory):
-    confoverrides = {"html_theme_options.google_analytics_id": "UA-XXXXX"}
+@pytest.mark.parametrize(
+    "provider,tags",
+    [
+        # TODO: Deprecate old-style analytics config >= 0.12
+        # new_google_analytics_id
+        ({"html_theme_options.google_analytics_id": "G-XXXXX"}, ["gtag", "G-XXXXX"]),
+        # old_google_analytics_id
+        ({"html_theme_options.google_analytics_id": "UA-XXXXX"}, ["ga", "UA-XXXXX"]),
+        # google analytics
+        (
+            {"html_theme_options.analytics": {"google_analytics_id": "G-XXXXX"}},
+            ["gtag", "G-XXXXX"],
+        ),
+        # plausible
+        (
+            {
+                "html_theme_options.analytics": {
+                    "plausible_analytics_domain": "toto",
+                    "plausible_analytics_url": "http://.../script.js",
+                }
+            },
+            ["data-domain", "toto"],
+        ),
+    ],
+)
+def test_analytics(sphinx_build_factory, provider, tags):
+    confoverrides = provider
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides)
     sphinx_build.build()
     index_html = sphinx_build.html_tree("index.html")
 
     # Search all the scripts and make sure one of them has the Google tag in there
     tags_found = False
     for script in index_html.select("script"):
-        if script.string and "ga" in script.string and "UA-XXXXX" in script.string:
+        if script.string and tags[0] in script.string and tags[1] in script.string:
             tags_found = True
     assert tags_found is True