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 below for relevant options depending on the analytics provider that you want to use.

html_theme_options = {
    # See below for options for each service
    "analytics": analytics_options,
}

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.

Get a self-hosted Plausible server at scientific-python.org

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 https://views.scientific-python.org/<your-package>. To ask about this, contact them on the social media platform of your choice and learn more at scientific-python.org.

Plausible Analytics#

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’s JavaScript will be included in all HTML pages to gather metrics. The dashboard with analytics results will be accessible at https://<plausible-url>/<my-domain>.

html_theme_options["analytics"] = {
    # 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",
}

See also

See the Plausible Documentation for more information about this script.

Google Analytics#

If the google_analytics_id config option is specified (like G-XXXXXXXXXX), Google Analytics’ JavaScript is included in the HTML pages.

html_theme_options["analytics"] = {
    "google_analytics_id": "G-XXXXXXXXXX",
}