Add plausible analytics #828

tupui · 2022-07-20T20:23:44Z

Closes #827

This adds Plausible analytics. I am not sure about what I did, but I think I edited all the files which needed to be edited 😅

cc @choldgraf @stefanv

tupui · 2022-07-20T21:50:10Z

So I am not sure what I am missing but this is failing:

E         + WARNING: unsupported theme option 'plausible_domain' given
[73](https://github.com/pydata/pydata-sphinx-theme/runs/7438329801?check_suite_focus=true#step:7:74)
E         + WARNING: unsupported theme option 'plausible_url' given

stefanv

Looks good to me @tupui! Some minor language tweaks in the docs.

docs/user_guide/analytics.rst

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

choldgraf · 2022-07-21T04:31:55Z

A quick thought on your error message. It looks like in your examples you're using analytics_domain but in theme.conf you're using plausible_analytics_domain. I think that's probably the error.

Can I get a quick gut-check on whether it'd be more sensible to nest these under a single analytics configuration value, so that we don't create new Sphinx configuration values each time we want to extend analytics functionality? e.g.:

html_theme_options = {
  "analytics": {"plausiable__analytics_domain": "foo", "plausible__analytics_url": "bar"},
}

or

html_theme_options = {
  "analytics": {"google_analytics_id": "foo"},
}

or is that over-engineering API? 😅

tupui · 2022-07-21T04:53:03Z

Thank you both for you reviews!

@stefanv I rephrased the doc. Let me know how it reads.

@choldgraf indeed! Sometimes... 😅 Let see now. For the configuration as you wish. I do think that what you propose would look cleaner, but then we need to think about backward compatibility. LMK if I should make the change. I would then raise a deprecation warning in case the other syntax is used.

I am looking at the tests. I will try to run these in debug locally. Not sure what I am doing there.

tupui · 2022-07-21T05:08:24Z

Ok I think I fixed it. This is adding the following, which I believe is correct:

 <script defer="defer">
             data-domain=toto src=http://.../script.js
         </script>,

choldgraf · 2022-07-21T05:53:53Z

Personally, I think it's be cleaner if we just defined a top level "analytics" config value. We already have large-ish top-level config surface area so this might help keep things a bit ordered. +1 on a deprecation cycle for the current Google analytics IDs. I don't feel strongly about it though, so if you or others disagree that it's a good idea, we can skip it. What do you think? 🙂

tupui · 2022-07-21T06:39:44Z

I also prefer to not grow the API, I made the change. (I just did not add a test to catch the warning itself. Not sure we really have to. LMK)

src/pydata_sphinx_theme/__init__.py

choldgraf

This looks good to me - I'm +1 after my minor comments are resolved.

docs/user_guide/analytics.rst

choldgraf · 2022-07-21T07:12:09Z

docs/user_guide/analytics.rst

+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


Is this documented somewhere? We were looking into Plausible for Jupyter a while back, but didn't do it in-part because it was pretty expensive to run at the scale of Jupyter's website. I wonder if we could piggy-back on scientific-python with this?

Documented as what is the process to get access? Nothing yet, this would be the first document talking about that. At some point we might have some mention on our website when we list all the initiatives we have.

@stefanv maybe you can answer this one? I don't know how hard this is for the server.
But I would guess it's ok. SciPy is getting 100k per month which is nothing. I don't know how many RPS the server can handle but I would assume >100 RPS (based on my personal experience, we should see this with e.g. locust to be sure)

docs/user_guide/analytics.rst

src/pydata_sphinx_theme/__init__.py

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

tests/test_build.py

Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>

tupui

Thank you for the review and suggestions Chris! I will work on that.

tests/test_build.py

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

src/pydata_sphinx_theme/__init__.py

docs/user_guide/analytics.rst

tupui · 2022-07-22T00:45:33Z

docs/user_guide/analytics.rst

+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


Documented as what is the process to get access? Nothing yet, this would be the first document talking about that. At some point we might have some mention on our website when we list all the initiatives we have.

@stefanv maybe you can answer this one? I don't know how hard this is for the server.
But I would guess it's ok. SciPy is getting 100k per month which is nothing. I don't know how many RPS the server can handle but I would assume >100 RPS (based on my personal experience, we should see this with e.g. locust to be sure)

tupui · 2022-07-22T02:18:34Z

Alright, I did the changes 😃

choldgraf

this looks pretty good to me! I have a few comments in there with suggestions and questions, let me know what you think!

docs/user_guide/analytics.rst

src/pydata_sphinx_theme/__init__.py

choldgraf · 2022-07-23T05:10:52Z

src/pydata_sphinx_theme/__init__.py

+                """
+
+            # Link the JS files
+            app.add_js_file(gid_js_path, loading_method="async")


is there a reason we'd use defer for plausible, but async here?

I copied this but apparently this is what they have in their doc. Maybe to have correct timing?? https://plausible.io/docs/plausible-script

Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>

tupui

Thank you for the suggestions!

tupui · 2022-07-23T06:45:41Z

src/pydata_sphinx_theme/__init__.py

+                """
+
+            # Link the JS files
+            app.add_js_file(gid_js_path, loading_method="async")


I copied this but apparently this is what they have in their doc. Maybe to have correct timing?? https://plausible.io/docs/plausible-script

docs/user_guide/analytics.rst

choldgraf · 2022-07-24T14:21:17Z

Thanks for the contribution! This looks good to me, let's see if there are some edge-cases to debug in the future

tupui · 2022-07-24T19:14:48Z

Great thanks Chris!

stefanv · 2022-07-24T20:33:30Z

docs/user_guide/analytics.rst

+
+   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
+   ``<your-package>.scientific-python.org``.


@tupui Note that we host all projects at views.scientific-python.org

Is there anything project-specific in a URL? Or just one big dashboard for everybody?

Ah yes it should be https://views.scientific-python.org/<your-package>

stefanv · 2022-07-24T20:34:03Z

docs/user_guide/analytics.rst

+- 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.


Incorrect usage of apostrophe

stefanv · 2022-07-24T20:35:02Z

src/pydata_sphinx_theme/__init__.py

-                ga('set', 'anonymizeIp', true);
-                ga('send', 'pageview');
+        msg = (
+            "'google_analytics_id' is deprecated and will be removed in "


Does this not affect the current Google Analytics section in the documentation?

mmm I did not update this indeed.

~~Correction, I mis-read that and I did update the doc about Google Analytics.~~ Ah no I see what you meant. Chris did it right in the follow-up

tupui

Thanks @stefanv I will make a follow up.

tupui · 2022-07-25T16:48:47Z

docs/user_guide/analytics.rst

+
+   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
+   ``<your-package>.scientific-python.org``.


Ah yes it should be https://views.scientific-python.org/<your-package>

tupui · 2022-07-25T16:49:15Z

src/pydata_sphinx_theme/__init__.py

-                ga('set', 'anonymizeIp', true);
-                ga('send', 'pageview');
+        msg = (
+            "'google_analytics_id' is deprecated and will be removed in "


mmm I did not update this indeed.

tupui added 3 commits July 20, 2022 13:25

Add plausible analytics

ad5ebe7

Merge remote-tracking branch 'upstream/main' into plausible_analytics

c18a35f

Add documentation for plausible analytics

04566ca

tupui force-pushed the plausible_analytics branch from 708b924 to 04566ca Compare July 20, 2022 20:26

Fix linter

52a7229

stefanv reviewed Jul 21, 2022

View reviewed changes

tupui added 2 commits July 20, 2022 21:39

Fix test

c1ef5c9

Rephrase doc and lint

584a59e

Fix tests

063a25b

Refactor analytics in a single parameter and deprecate old way

ba17514

tupui force-pushed the plausible_analytics branch from 27bf383 to ba17514 Compare July 21, 2022 06:39

tupui commented Jul 21, 2022

View reviewed changes

src/pydata_sphinx_theme/__init__.py Outdated Show resolved Hide resolved

choldgraf approved these changes Jul 21, 2022

View reviewed changes

choldgraf mentioned this pull request Jul 21, 2022

remove analytics jupyter/jupyter.github.io#408

Merged

Apply suggestions from code review

ee187e9

Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>

tupui commented Jul 22, 2022

View reviewed changes

tupui added 2 commits July 21, 2022 17:56

Scientific Python admonition and plausible

efe5bda

Simplify analytics logic and add more tests

c4b0e3c

choldgraf reviewed Jul 23, 2022

View reviewed changes

Apply suggestions from code review

5a15ba9

Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>

tupui commented Jul 23, 2022

View reviewed changes

choldgraf reviewed Jul 24, 2022

View reviewed changes

docs/user_guide/analytics.rst Outdated Show resolved Hide resolved

Update docs/user_guide/analytics.rst

2b00d99

choldgraf merged commit 75c7754 into pydata:main Jul 24, 2022

stefanv reviewed Jul 24, 2022

View reviewed changes

choldgraf mentioned this pull request Jul 25, 2022

Clarify analytics documentation #839

Merged

tupui commented Jul 25, 2022

View reviewed changes

tupui deleted the plausible_analytics branch July 25, 2022 16:49

jarrodmillman added this to the 0.10 milestone Jul 26, 2022

tkoyama010 mentioned this pull request Nov 21, 2022

Move google_analytics_id to analytics in pydata-sphinx-theme pyvista/pyvista#3634

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add plausible analytics #828

Add plausible analytics #828

tupui commented Jul 20, 2022 •

edited

tupui commented Jul 20, 2022

stefanv left a comment

choldgraf commented Jul 21, 2022

tupui commented Jul 21, 2022

tupui commented Jul 21, 2022

choldgraf commented Jul 21, 2022

tupui commented Jul 21, 2022 •

edited

choldgraf left a comment

choldgraf Jul 21, 2022

tupui Jul 22, 2022

tupui left a comment

tupui Jul 22, 2022

tupui commented Jul 22, 2022

choldgraf left a comment

choldgraf Jul 23, 2022

tupui Jul 23, 2022

tupui left a comment

tupui Jul 23, 2022

choldgraf commented Jul 24, 2022

tupui commented Jul 24, 2022

stefanv Jul 24, 2022

choldgraf Jul 25, 2022

tupui Jul 25, 2022

stefanv Jul 24, 2022

stefanv Jul 24, 2022

tupui Jul 25, 2022

tupui Jul 25, 2022 •

edited

tupui left a comment

tupui Jul 25, 2022

tupui Jul 25, 2022

Add plausible analytics #828

Add plausible analytics #828

Conversation

tupui commented Jul 20, 2022 • edited

tupui commented Jul 20, 2022

stefanv left a comment

Choose a reason for hiding this comment

choldgraf commented Jul 21, 2022

tupui commented Jul 21, 2022

tupui commented Jul 21, 2022

choldgraf commented Jul 21, 2022

tupui commented Jul 21, 2022 • edited

choldgraf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tupui left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tupui commented Jul 22, 2022

choldgraf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tupui left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Jul 24, 2022

tupui commented Jul 24, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tupui Jul 25, 2022 • edited

Choose a reason for hiding this comment

tupui left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tupui commented Jul 20, 2022 •

edited

tupui commented Jul 21, 2022 •

edited

tupui Jul 25, 2022 •

edited