Read the Docs, Deprecation: Removal of Sphinx context injection at build time

evbauer commented 2 months ago

July 16 email from Read the Docs copied below:

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:

mesa-doc

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.

Contact us or reply to this email if you have any questions or feedback about this change.

evbauer commented 2 months ago

So I guess we just need to add this to docs/source/conf.py to keep everything going normally?

# 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

pmocz commented 1 month ago

That looks right! I can go ahead and patch this

MESAHub / mesa