From ad5ebe7139d28460958d51202e7e7be9dfec1274 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Wed, 20 Jul 2022 13:22:31 -0700 Subject: [PATCH 01/12] Add plausible analytics --- src/pydata_sphinx_theme/__init__.py | 11 +++++++++++ .../theme/pydata_sphinx_theme/theme.conf | 2 ++ tests/test_build.py | 17 +++++++++++++++++ 3 files changed, 30 insertions(+) diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 32ea3702e..6da58252f 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -77,6 +77,17 @@ def update_config(app, env): app.add_js_file(gid_js_path, loading_method="async") app.add_js_file(None, body=gid_script) + # or Plausible analytics + plausible_domain = theme_options.get("plausible_domain") + plausible_url = theme_options.get("plausible_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") + def prepare_html_config(app, pagename, templatename, context, doctree): """Prepare some configuration values for the HTML build. diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf index 8fde846ae..a0a467605 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf @@ -18,6 +18,8 @@ twitter_url = icon_links_label = Icon Links icon_links = google_analytics_id = +plausible_analytics_domain= +plausible_analytics_url= favicons = show_prev_next = True search_bar_text = Search the docs ... diff --git a/tests/test_build.py b/tests/test_build.py index 5e7f726d2..794229a28 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -568,6 +568,23 @@ def test_old_google_analytics_id(sphinx_build_factory): assert tags_found is True +def test_plausible_analytics_id(sphinx_build_factory): + confoverrides = { + "html_theme_options.plausible_domain": "toto", + "html_theme_options.plausible_url": "http://.../script.js" + } + 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 plausible domain + tags_found = False + for script in index_html.select("script"): + if script.string and "data-domain" in script.string and "toto" in script.string: + tags_found = True + assert tags_found is True + + def test_show_nav_level(sphinx_build_factory): """The navbar items align with the proper part of the page.""" confoverrides = {"html_theme_options.show_nav_level": 2} From 04566ca6de17ea2f37a1af88120151b363872ceb Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Wed, 20 Jul 2022 13:26:27 -0700 Subject: [PATCH 02/12] Add documentation for plausible analytics --- docs/user_guide/analytics.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst index 3016ddf91..6fecffe02 100644 --- a/docs/user_guide/analytics.rst +++ b/docs/user_guide/analytics.rst @@ -12,3 +12,20 @@ Google Analytics' javascript is included in the html pages. html_theme_options = { "google_analytics_id": "G-XXXXXXXXXX", } + +Plausible Analytics +=================== + +Alternatively https://plausible.io can be used to gather simple +and privacy-friendly analytics for the site. The dashboard can be accessed +at ``url/domain``. +The Scientific-Python community can offer a self-hosted server. + +Plausible' javascript is included in the html pages. + +.. code:: python + + html_theme_options = { + "plausible_analytics_domain": "my-domain", + "plausible_analytics_url": "https://.../script.js", + } From 52a72291ab04add0a507b9089de2b49257464d1c Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Wed, 20 Jul 2022 14:26:09 -0700 Subject: [PATCH 03/12] Fix linter --- tests/test_build.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_build.py b/tests/test_build.py index 794229a28..d65df854c 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -571,7 +571,7 @@ def test_old_google_analytics_id(sphinx_build_factory): def test_plausible_analytics_id(sphinx_build_factory): confoverrides = { "html_theme_options.plausible_domain": "toto", - "html_theme_options.plausible_url": "http://.../script.js" + "html_theme_options.plausible_url": "http://.../script.js", } sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides) sphinx_build.build() From c1ef5c99066675357aa5a6941b093e72c6d774a2 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Wed, 20 Jul 2022 21:39:46 -0700 Subject: [PATCH 04/12] Fix test --- tests/test_build.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_build.py b/tests/test_build.py index d65df854c..1b57d8bc4 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -570,8 +570,8 @@ def test_old_google_analytics_id(sphinx_build_factory): def test_plausible_analytics_id(sphinx_build_factory): confoverrides = { - "html_theme_options.plausible_domain": "toto", - "html_theme_options.plausible_url": "http://.../script.js", + "html_theme_options.plausible_analytics_domain": "toto", + "html_theme_options.plausible_analytics_url": "http://.../script.js", } sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides) sphinx_build.build() From 584a59e6b94c0b1ac7c42e4542508796c7606e98 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Wed, 20 Jul 2022 21:48:32 -0700 Subject: [PATCH 05/12] Rephrase doc and lint --- docs/user_guide/analytics.rst | 10 ++++++---- .../theme/pydata_sphinx_theme/theme.conf | 4 ++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst index 6fecffe02..10c2ab54c 100644 --- a/docs/user_guide/analytics.rst +++ b/docs/user_guide/analytics.rst @@ -17,11 +17,13 @@ Plausible Analytics =================== Alternatively https://plausible.io can be used to gather simple -and privacy-friendly analytics for the site. The dashboard can be accessed -at ``url/domain``. -The Scientific-Python community can offer a self-hosted server. +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``. -Plausible' javascript is included in the html pages. +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 diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf index a0a467605..205e4ea93 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf @@ -18,8 +18,8 @@ twitter_url = icon_links_label = Icon Links icon_links = google_analytics_id = -plausible_analytics_domain= -plausible_analytics_url= +plausible_analytics_domain = +plausible_analytics_url = favicons = show_prev_next = True search_bar_text = Search the docs ... From 063a25b813f2edda520ef49f78bd2eaf81ca5858 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Wed, 20 Jul 2022 22:06:55 -0700 Subject: [PATCH 06/12] Fix tests --- src/pydata_sphinx_theme/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 6da58252f..7fd562748 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -78,8 +78,8 @@ def update_config(app, env): app.add_js_file(None, body=gid_script) # or Plausible analytics - plausible_domain = theme_options.get("plausible_domain") - plausible_url = theme_options.get("plausible_url") + plausible_domain = theme_options.get("plausible_analytics_domain") + plausible_url = theme_options.get("plausible_analytics_url") if plausible_domain and plausible_url: plausible_script = f""" From ba175148167d33def6fa0bee78d9d0419c68c02b Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Wed, 20 Jul 2022 23:36:14 -0700 Subject: [PATCH 07/12] Refactor analytics in a single parameter and deprecate old way --- docs/user_guide/analytics.rst | 30 ++++--- src/pydata_sphinx_theme/__init__.py | 84 +++++++++++-------- .../theme/pydata_sphinx_theme/theme.conf | 3 +- tests/test_build.py | 62 +++++++------- 4 files changed, 100 insertions(+), 79 deletions(-) diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst index 10c2ab54c..cfe56b65b 100644 --- a/docs/user_guide/analytics.rst +++ b/docs/user_guide/analytics.rst @@ -1,22 +1,20 @@ Analytics and usage services ============================ -Google Analytics -================ - -If the ``google_analytics_id`` config option is specified (like ``G-XXXXXXXXXX``), -Google Analytics' javascript is included in the html pages. +The theme supports analytics via the ``analytics`` option. It is configured +by passing a dictionary with options. See the sections bellow for relevant +options depending on the analytic provider that you want to use. .. code:: python html_theme_options = { - "google_analytics_id": "G-XXXXXXXXXX", + "analytics": analytics_options, } -Plausible Analytics -=================== +Plausible Analytics (recommended) +================================= -Alternatively https://plausible.io can be used to gather simple +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 @@ -27,7 +25,19 @@ team on social media following https://scientific-python.org for assistance. .. code:: python - html_theme_options = { + analytics_options = { "plausible_analytics_domain": "my-domain", "plausible_analytics_url": "https://.../script.js", } + +Google Analytics +================ + +If the ``google_analytics_id`` config option is specified (like ``G-XXXXXXXXXX``), +Google Analytics' javascript is included in the html pages. + +.. code:: python + + analytics_options = { + "google_analytics_id": "G-XXXXXXXXXX", + } diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 7fd562748..3bc7ad99c 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/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,44 +50,61 @@ 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 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") - # or Plausible analytics - plausible_domain = theme_options.get("plausible_analytics_domain") - plausible_url = theme_options.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") + 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): diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf index 205e4ea93..21daefc29 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf @@ -18,8 +18,7 @@ twitter_url = icon_links_label = Icon Links icon_links = google_analytics_id = -plausible_analytics_domain = -plausible_analytics_url = +analytics = favicons = show_prev_next = True search_bar_text = Search the docs ... diff --git a/tests/test_build.py b/tests/test_build.py index 1b57d8bc4..bf049ab79 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -540,22 +540,33 @@ 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", + [ + # deprecated + # 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") @@ -563,24 +574,7 @@ def test_old_google_analytics_id(sphinx_build_factory): # 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: - tags_found = True - assert tags_found is True - - -def test_plausible_analytics_id(sphinx_build_factory): - confoverrides = { - "html_theme_options.plausible_analytics_domain": "toto", - "html_theme_options.plausible_analytics_url": "http://.../script.js", - } - 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 plausible domain - tags_found = False - for script in index_html.select("script"): - if script.string and "data-domain" in script.string and "toto" 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 From ee187e96a650176c0c3dc5f248028332bea938a3 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Thu, 21 Jul 2022 17:40:01 -0700 Subject: [PATCH 08/12] Apply suggestions from code review Co-authored-by: Chris Holdgraf --- docs/user_guide/analytics.rst | 6 ++++-- src/pydata_sphinx_theme/__init__.py | 1 + tests/test_build.py | 2 +- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst index cfe56b65b..bc5ce5b24 100644 --- a/docs/user_guide/analytics.rst +++ b/docs/user_guide/analytics.rst @@ -1,9 +1,9 @@ Analytics and usage services ============================ -The theme supports analytics via the ``analytics`` option. It is configured +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 analytic provider that you want to use. +options depending on the analytics provider that you want to use. .. code:: python @@ -25,6 +25,7 @@ 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", @@ -38,6 +39,7 @@ Google Analytics' javascript is included in the html pages. .. code:: python + # To be re-used in html_theme_options["analytics"] analytics_options = { "google_analytics_id": "G-XXXXXXXXXX", } diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 3bc7ad99c..1e7d4c37f 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -52,6 +52,7 @@ def update_config(app, env): # Add an analytics ID to the site if provided # deprecated options for Google Analytics + # TODO: deprecate >= v0.12 gid = theme_options.get("google_analytics_id") if gid: msg = ( diff --git a/tests/test_build.py b/tests/test_build.py index bf049ab79..459ab6cb6 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -543,7 +543,7 @@ def test_edit_page_url(sphinx_build_factory, html_context, edit_url): @pytest.mark.parametrize( "provider,tags", [ - # deprecated + # 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 From efe5bda05c22131e9c5586d31683bff5aacf268f Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Thu, 21 Jul 2022 17:50:11 -0700 Subject: [PATCH 09/12] Scientific Python admonition and plausible --- docs/user_guide/analytics.rst | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst index bc5ce5b24..92250b7bd 100644 --- a/docs/user_guide/analytics.rst +++ b/docs/user_guide/analytics.rst @@ -11,8 +11,22 @@ options depending on the analytics provider that you want to use. "analytics": analytics_options, } -Plausible Analytics (recommended) -================================= +Generally speaking we recommend using Plausible over Google Analytics because +it has a better story around user security and privacy. In addition, it is more +open-source and transparent. In fact, +`you can self-host a Plausible server `__. + +.. admonition:: Get a self-hosted Plausible server at ``scientific-python.org`` + :class: tip + + If your documentation is for a package that is part of the SciPy / PyData + ecosystem, they might be able to host a Plausible server for you at + `.scientific-python.org`. + To ask about this, contact them on the social media platform of your choice + and learn more at `scientific-python.org `__. + +Plausible Analytics +=================== https://plausible.io can be used to gather simple and privacy-friendly analytics for the site. The configuration consists in @@ -20,9 +34,6 @@ 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"] From c4b0e3c6170205caf67a221f01c6da8812d1b460 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Thu, 21 Jul 2022 18:01:57 -0700 Subject: [PATCH 10/12] Simplify analytics logic and add more tests --- src/pydata_sphinx_theme/__init__.py | 8 ++----- .../theme/pydata_sphinx_theme/theme.conf | 4 +++- tests/test_build.py | 22 +++++++++++++++++++ 3 files changed, 27 insertions(+), 7 deletions(-) diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 1e7d4c37f..9fea03dfe 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -50,7 +50,7 @@ def update_config(app, env): ) # Add an analytics ID to the site if provided - + analytics = theme_options.get("analytics", {}) # deprecated options for Google Analytics # TODO: deprecate >= v0.12 gid = theme_options.get("google_analytics_id") @@ -61,12 +61,8 @@ def update_config(app, env): "and use 'analytics' instead." ) warnings.warn(msg, DeprecationWarning, stacklevel=2) - if theme_options.get("analytics"): - theme_options["analytics"].update({"google_analytics_id": gid}) - else: - theme_options["analytics"] = {"google_analytics_id": gid} + analytics.update({"google_analytics_id": gid}) - analytics = theme_options.get("analytics") if analytics: # Plausible analytics plausible_domain = analytics.get("plausible_analytics_domain") diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf index 21daefc29..7908fc168 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf @@ -17,7 +17,6 @@ gitlab_url = twitter_url = icon_links_label = Icon Links icon_links = -google_analytics_id = analytics = favicons = show_prev_next = True @@ -44,3 +43,6 @@ announcement = # DEPRECATE after 0.11 logo_text = + +# DEPRECATE after 0.12 +google_analytics_id = diff --git a/tests/test_build.py b/tests/test_build.py index 459ab6cb6..1fea01388 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -563,6 +563,28 @@ def test_edit_page_url(sphinx_build_factory, html_context, edit_url): }, ["data-domain", "toto"], ), + # google and plausible + ( + { + "html_theme_options.analytics": { + "google_analytics_id": "G-XXXXX", + "plausible_analytics_domain": "toto", + "plausible_analytics_url": "http://.../script.js", + } + }, + ["gtag", "G-XXXXX"], + ), + # TODO: Deprecate old-style analytics config >= 0.12 + ( + { + "html_theme_options.analytics": { + "plausible_analytics_domain": "toto", + "plausible_analytics_url": "http://.../script.js", + }, + "html_theme_options.google_analytics_id": "G-XXXXX", + }, + ["gtag", "G-XXXXX"], + ), ], ) def test_analytics(sphinx_build_factory, provider, tags): From 5a15ba9ebb6d04ae1a5430b32613d41be3706173 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Fri, 22 Jul 2022 23:43:42 -0700 Subject: [PATCH 11/12] Apply suggestions from code review Co-authored-by: Chris Holdgraf --- docs/user_guide/analytics.rst | 22 ++++++++++++++++------ src/pydata_sphinx_theme/__init__.py | 1 + 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst index 92250b7bd..60bc36d3c 100644 --- a/docs/user_guide/analytics.rst +++ b/docs/user_guide/analytics.rst @@ -8,6 +8,7 @@ options depending on the analytics provider that you want to use. .. code:: python html_theme_options = { + # See below for options for each service "analytics": analytics_options, } @@ -21,27 +22,36 @@ open-source and transparent. In fact, If your documentation is for a package that is part of the SciPy / PyData ecosystem, they might be able to host a Plausible server for you at - `.scientific-python.org`. + ``.scientific-python.org``. To ask about this, contact them on the social media platform of your choice and learn more at `scientific-python.org `__. Plausible Analytics =================== -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``. +`plausible.io `__ can be used to gather simple +and privacy-friendly analytics for the site. To configure, you will need to provide two things: + +- A URL pointing to the JavaScript analytics script that is served by your Plausible server +- A domain that reflects where your documentation lives + +Plausible' javascript will be included in all html pages to gather metrics. +The dashboard with analytics results will be accessible at ``https:///``. .. code:: python # To be re-used in html_theme_options["analytics"] analytics_options = { + # The domain you'd like to use for this analytics instance "plausible_analytics_domain": "my-domain", + # The analytics script that is served by Plausible "plausible_analytics_url": "https://.../script.js", } +.. seealso:: + + See the ``Plausible Documentation `__ for more information about this script. + Google Analytics ================ diff --git a/src/pydata_sphinx_theme/__init__.py b/src/pydata_sphinx_theme/__init__.py index 9fea03dfe..59b8e15c1 100644 --- a/src/pydata_sphinx_theme/__init__.py +++ b/src/pydata_sphinx_theme/__init__.py @@ -68,6 +68,7 @@ def update_config(app, env): plausible_domain = analytics.get("plausible_analytics_domain") plausible_url = analytics.get("plausible_analytics_url") + # Ref: https://plausible.io/docs/plausible-script if plausible_domain and plausible_url: plausible_script = f""" data-domain={plausible_domain} src={plausible_url} From 2b00d992274112f05ac97d45171f7025524290d2 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sun, 24 Jul 2022 06:13:27 -0700 Subject: [PATCH 12/12] Update docs/user_guide/analytics.rst --- docs/user_guide/analytics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst index 60bc36d3c..6e18ab4f5 100644 --- a/docs/user_guide/analytics.rst +++ b/docs/user_guide/analytics.rst @@ -50,7 +50,7 @@ The dashboard with analytics results will be accessible at ``https://`__ for more information about this script. + See the `Plausible Documentation `__ for more information about this script. Google Analytics ================