Update Read the Docs config before Oct 2024

[kd-ods]

We need to adjust our ReadTheDocs configuration. Here is their announcement:

We are announcing the deprecation of Sphinx context injection at build time for all the projects. The deprecation date is set on Monday, October 7th, 2024. After this date, Read the Docs won't install the readthedocs-sphinx-ext extension and won't manipulate the project's conf.py file.

This will get us closer to our goal of having all projects build on Read the Docs be the exact same as on other build environments, making understanding of documentation builds much easier to understand.

You can read our blog post on the deprecation for all the information about possible impacts of this change, in particular the READTHEDOCS and other variables in the Sphinx context are no longer set automatically.

Deprecation timeline

We understand this change will affect thousands of projects, so we have a timeline to communicate this deprecation to our users effectively.

July 29, 2024: disable Sphinx context injection and enable Read the Docs Addons for all new projects created.
October 7, 2024: disable Sphinx context injection and enable Read the Docs Addons for all projects.

Are my projects affected?

You have at least one project with a canonical custom domain defined. After the deprecation date, Read the Docs will stop defining html_baseurl Sphinx configuration, which means that you will need to define it by yourself to keep the canonical custom domain properly configured.

We found the following projects where you are a maintainer are impacted by this change:

beneficial-ownership-data-standard

How I can update my projects?

You can use the following Python snippet as a guide to update your conf.py file. The snippet uses the READTHEDOCS_CANONICAL_URL environment variable to define html_baseurl and injects READTHEDOCS variable into the html_context to keep the previous behavior:

import os

# Set canonical URL from the Read the Docs Domain
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")

# Tell Jinja2 templates the build is running on Read the Docs
if os.environ.get("READTHEDOCS", "") == "True":
    html_context["READTHEDOCS"] = True

Closing notes

We recommend you to read the full announcement Read the Docs Addons enabled by default in our blog that contains a more detailed explanation and other similar changes that may affect other projects you maintain as well.

[kd-ods]

@rhiaro (or @radix0000) - Does one of you have time in the next month or two to pick this up? Looks like a small update is needed.

[kd-ods]

Just noting that @radix0000 is looking at this - thank you!