search

MAAP-Project / maap-documentation

Apache License 2.0
10 stars 13 forks source link

ReadTheDocs Sphinx Config Updates #417

Open wildintellect opened 4 months ago

wildintellect commented 4 months ago

https://about.readthedocs.com/blog/2024/07/addons-by-default/

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:

[maap-project](https://readthedocs.org/projects/maap-project/)

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.

wildintellect commented 1 month ago

443