Repository: scikit-hep/awkward

Issue:
Add statistics tracker to the new website
### Which documentation?

Tutorials site

### What needs to be documented?

Stefan gave us a `data-domain` for Plausible; we should add this text

```html
<script defer data-domain="awkward-array.org" src="https://views.scientific-python.org/js/plausible.js"></script>
```

to every HTML page. The HTML is generated by Sphinx, so it has to go into a template somewhere. I think we don't actually have the default HTML templates; I think that all of the HTML in [docs-sphinx/_templates](https://github.com/scikit-hep/awkward/tree/main/docs-sphinx/_templates) is an override. For instance, the [breadcrumbs.html](https://github.com/scikit-hep/awkward/blob/main/docs-sphinx/_templates/breadcrumbs.html) is just to eliminate something that would be on the default page (the "fork me on GitHub" ribbon?).

@agoose77, you've recently added [funding.html](https://github.com/scikit-hep/awkward/blob/main/docs-sphinx/_templates/funding.html), which appears at the bottom of every page. (I just checked.) If the `<script>` is added there, I think it would reach every page.

Except redirects. The [redirect.html](https://github.com/scikit-hep/awkward/blob/main/docs-sphinx/_templates/redirect.html) describes an entire page. It's debatable whether we'd want to count redirects. It would tell us how many people are using old URLs versus new URLs, but I don't see how useful that information is, and it would have to be disaggregated from the totals, since redirected links shouldn't be counted twice if we're interested in how many people went to a given _topic_ (not _page_). I vote for no statistics on redirects, and I'm not even sure if the script will work if the redirect happens through the meta mechanism (because such an access has `<noscript>`.

Arguably, a `<script>` element ought to go in the HTML `<head>`, rather than the `<body>` (`footer.html`). That's where I usually see them. Actually, I stand corrected: they're legal anywhere, and there are reasons to put them in the `<body>`. [This StackOverflow post](https://stackoverflow.com/a/24070373/1623645) presents the pros and cons: page rendering will pause while a script is being downloaded an executed, and that's no good. We could follow that page's "antiquated recommendation" by putting the `<script>` at the end of the page (`footer.html`); the reason against it doesn't apply: we don't need the statistics-counter script to run to render the page—that can happen late. The "modern approach" is to use `async` or `defer`, which I just noticed is in our snippet, so there are no constraints on when this snippet can be placed. (And it could be `async`, rather than `defer`, because we don't care whether it runs before or after other scripts on the page.)

The only argument I can see for putting it in the `<head>`, then, is that if the statistics-counter starts too late, we could undercount our bounce rate: users click the back button before rendering gets to the `<script>` and the page view gets counted. There will always be some cut-off in the bounce rate, much like $p_T$ in a tracking distribution, since very small values are hard to measure. Having a lower implicit cut on bounce rate, rather than a higher implicit cut, doesn't sound very important to me.

Trying to get it into the `<head>` would mean overloading more templates, and I don't like to overload Sphinx templates because it means we no longer get version updates for that part of the page, and who knows if the template designer intends some relationship between two parts of a page, starting with a particular version number? So I'm in favor of adding the `<script>` to `footer.html`, and `defer` may be replaced by `async` just to loosen an unnecessary constraint for the browser.

Sorry for the long-winded write-up; just thinking through the issues while I type!

Oh, one last thing: let's add the statistics-counter to the new documentation _only_. In other words, _not_ the one with the `latest` tag. The v1 documentation (`latest`) is split between two sites, I don't want to add it to the Netlify site, and the statistics will be easier to interpret if we have it on only one site: we'll know what page is meant by a given URL. We should also see the turn-on curve when the new documentation goes public. If we include the old documentation, we might not be able to filter it out of the statistics, since some of the URLs are the same.


Discussion:

Resolving patch:
diff --git a/docs-sphinx/conf.py b/docs-sphinx/conf.py
--- a/docs-sphinx/conf.py
+++ b/docs-sphinx/conf.py
@@ -89,6 +89,10 @@
             "url": "https://github.com/scikit-hep/awkward/releases",
         },
     ],
+    "analytics": {
+        "plausible_analytics_domain": "awkward-array.org",
+        "plausible_analytics_url": "https://views.scientific-python.org/js/plausible.js"
+    }
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,


Test patch: