Add Plausible statistics-counter to all HTML pages

[jpivarski]

Stefan gave us a data-domain for scikit-hep.org; this snippet should be added to every HTML page:

<script defer data-domain="scikit-hep.org" src="https://views.scientific-python.org/js/plausible.js"></script>

It doesn't matter where on the page it appears (see a long conversation I had with myself here: scikit-hep/awkward#1819), and I think the defer could be replaced by async. You just need to find a template that gets rendered on every page you care about. (In my long conversation, I decided that I didn't care about redirects, but that's up to you.) There are templates in _includes and _layouts.

---

By the way—context for anyone seeing this without background—this is a follow-up of a discussion we had on the Scikit-HEP administrators list. The scientific-python.org organization is providing website statistics through Plausible, which we can use on our documentation sites. The reason we want it is to get a sense of what our users are interested in. In particular, the Awkward Array library is organized as a collection of ak.* functions, each with its own page; if we find 100× more website traffic to ak.this than ak.that, then we'll know that ak.this is more important (should get more developer attention) than ak.that. The usefulness to the scikit-hep.org pages is different: "Are users looking at 'Project News'? 'Packages'? 'User Information'? ...)

In the presentations at SciPy, they said that Plausible is less intrusive than Google Analytics (which I've used in the past). In particular, Google Analytics violates some regulations in Europe, but Plausible does not. So the choices seem to be well thought-through.

[jpivarski]

:bump: I highly recommend this, because if you want the data later, you'll have to have set it up earlier.

Here's what the output looks like for Awkward Array's documentation:

We learn, for instance, that there's a strong weekday/weekend effect—people who are working—that the documentation is being read primarily in the United States (odd... is there a U.S./Europe split on Awkward Array? something to look into...),¹ that most users are accessing it with Windows—also a surprise, since most of the physicists I know have Macs—that they get to the documentation by direct searches (good; it's intentional), an average bounce rate, and that most people are going into the User Guide, not the Reference, which is much more complete. At the very least, we'll perhaps need to fill our our blank User Guide pages with pointers to the Reference, since that's where people are looking.

Footnotes

1. No: I should be comparing the U.S. to the sum of European countries, maybe with special attention to Switzerland. The absolute numbers should be weighted by estimated physicists-per-country... ↩

[eduardo-rodrigues]

Thanks Jim. Very interesting! I was going to make the comment that Europe is indeed the sum of several. Overall the difference Europo-US is not that large. But I was expecting quite more hits from Switzerland for people posted at CERN; that's unexpected.
Another curiosity is the large number of visitors from the UK and the even reasonably larger number from Germany. Would the latter be thanks to Belle II colleagues?

I have no idea why Windows is so prominent. Is it because several colleagues have Windows laptops or rather desktops in the office. I do but know I am a clear minority around me.

A couple of questions:

1. You need some special account to access these summaries, I guess? Something others here can do as well? The exercise would be particularly interesting for packages with large visibility such as iminuit (@HDembinski) or pyhf (@matthewfeickert)
2. You say above that there are templates on the website but I did not see them. Can you point to an example from the site or Ackward Array's? Are you in fact going to add such stats-counters to the org site, by chance?

[HDembinski]

Thanks for the ping, this is indeed very interesting. I should try to add that to the iminuit docs.

[jpivarski]

@eduardo-rodrigues and @HDembinski, you need to be able to access https://views.scientific-python.org/, and you might need to contact Stéfan van der Walt (webpage, GitHub, Discord: stefanv#0829) for that. I had this conversation with him (last year) on Discord.

We don't need any additional help (beyond accessing the dashboard) for the generic Scikit-HEP pages; we just need to get this text into the HTML of all the pages:

<script defer data-domain="scikit-hep.org" src="https://views.scientific-python.org/js/plausible.js"></script>

The scikit-hep.org data domain has already been created in Plausible and is waiting for data. The easiest way to get it on all of the Scikit-HEP pages is to add it to one of the templates, but which one depends on how this Jekyll site works. Maybe _layouts/page.html? Maybe _includes/head.html and _includes/head_custom.html?

Since iminuit has a large community apart from Scikit-HEP (not disjoint, but another large cluster), I think you'll want a specialized iminuit (iminuit.readthedocs.io?) data domain, since each of these data domains is a separate bucket for aggregating statistics and I think you'll want to see iminuit statistics separately from Scikit-HEP statistics (just as we do for Awkward). That would be another thing to ask Stéfan.

[HDembinski]

The scikit-hep.org data domain has already been created in Plausible and is waiting for data. The easiest way to get it on all of the Scikit-HEP pages is to add it to one of the templates, but which one depends on how this Jekyll site works. Maybe _layouts/page.html? Maybe _includes/head.html and _includes/head_custom.html?

@jpivarski I assume this is related to the scikit-hep.org website. Do you also know how I can inject the line
<script defer data-domain="scikit-hep.org" src="https://views.scientific-python.org/js/plausible.js"></script>
into sphinx-generated documentation? I was browsing https://www.sphinx-doc.org/en/master/usage/configuration.html and I could not find an option to customize the website head.

In Markdown, it is possible inject arbitrary html code into the markdown code, but my docs are written in RST and I don't know how to do that in RST.

[jpivarski]

It looks like you could use this Sphinx extension: sphinx-plausible.

I also looked up "Google Analytics in Sphinx" and found this, since it's a matter of adding a <script> tag in either case.

I don't know that it needs to be in the <head>. In Awkward Array's documentation, it is in the <head>, but the Javascript would run if it were in the <body> as well; it would just start later (which might even be preferable, from a page load speed perspective).

[matthewfeickert]

@jpivarski while I'm going to try to use sphinx-plausible can you link to the PR that you used for Awkward?

[matthewfeickert]

It doesn't matter where on the page it appears (see a long conversation I had with myself here: scikit-hep/awkward#1819), and I think the defer could be replaced by async

Woops never mind. This is scikit-hep/awkward#1822.

[matthewfeickert]

pyhf is now reporting at: https://views.scientific-python.org/pyhf.readthedocs.io/