Read the Docs integration may potentially break in the future

[humitos]

Hi 👋🏼, I work at Read the Docs and I want to communicate some deprecation we are planning to do. We want to coordinate with this (and other) themes to avoid breaking changes and make the transition as smooth as possible.

I will write a small non-super-detailed sections per deprecation, but I'm happy to go deeper in details if you want me to expand on something in particular. My idea here is to start this conversation as a first step 👍🏼

Remove auto-injected Sphinx html_context

In simple words, we are removing the manipulation of the conf.py file that Read the Docs performs behind the scenes on each build. This manipulation appends the following file to the project's conf.py file: https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl

This manipulation performs the following:

• There are some workarounds to support old versions of Sphinx
• Injects plenty of variables in the html_context
• Adds _static directory to html_static_path if it exists
• Sets alabaster theme if there is no theme defined
• Set html_baseurl as canonical_url if Sphinx >=1.8
• Install readthedocs_ext.readthedocs as a Sphinx extension
• Install readthedocs_ext.external_version_warning if the Read the Docs version is external
• Define some LaTeX configurations based on project's language

The relevant manipulation for furo theme is the one that it's in bold. In particular, because some context variables are used by furo: github_version, github_user, github_repo, conf_py_path and maybe others. I found these at https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/components/edit-this-page.html#L23

In this particular case, the environment variable READTHEDOCS_GIT_CLONE_URL that Read the Docs exposes to the build process may be useful as a replacement for this --but probably more environment variables will be needed to expose here.

Note

We've already done a similar deprecation for MkDocs some days ago by removing the manipulation of mkdocs.yml. On the MkDocs side it was a little easier since we don't have so many MkDocs projects on Read the Docs, but also because we were doing less manipulation there. We wrote a blog post about this at https://about.readthedocs.com/blog/2024/03/mkdocs-yaml-manipulation/

Read the Docs embeded flyout replaced by new beta addons

We are moving away from the HTML blob injection we are currently doing to generate the flyout into a #readthedocs-embed-flyout selector (see https://docs.readthedocs.io/en/stable/flyout-menu.html). We already implemented Read the Docs Addons as a replacement to this approach which is modular and customizable (read more about these first steps in our blog: https://blog.readthedocs.com/addons-flyout-menu-beta/)

The removal of the HTML blob injection means that the files src/furo/theme/furo/sidebar/rtd-versions.html and src/furo/theme/furo/sidebar/variant-selector.html will need to be adapted to use the new addons approach. This new approach consists on subscribing to a JavaScript event and use the event.detail.data() to generate the HTML UI elements using the data exposed by Read the Docs Addons.

Examples on other Sphinx themes:

• Re-write of the HTML blob flyout using addons while keeping the same style in the sphinx-rtd-theme: Addons: integrate with new beta addons flyout readthedocs/sphinx_rtd_theme#1526
• Render language/version selectors using Read the Docs addons data on CPython documentation: Doc: Render version/language selector on Read the Docs python/cpython#116966

EthicalAds

I don't have all the details about EthicalAds yet, but I know that with the switch to addons, the file readthedocs/core/static-src/core/js/doc-embed/sponsorship.js won't be included anymore. This file makes the ad customization possible at this file src/furo/theme/furo/sidebar/ethical-ads.html in this theme.

The addons approach already includes the EthicalAds JavaScript client, which I understand that will keep working fine since furo is using [data-ea-publisher] already. I will confirm when I have more information about this, tho.

---

Please, let me know if you have any question here and/or if I can help in any other way to coordinate this work.

Related issues

• Fix edit button on Read the Docs with stable branch builds #668
• Create version selection menu as a configuration option #372

[pradyunsg]

Does this mean you no longer inject READTHEDOCS context variables into the build process either?

[humitos]

The Sphinx READTHEDOCS HTML context variable (html_context["READTHEDOCS"]) won't be included anymore, yeah. However, the READTHEDOCS environment variable will continue to be passed to the commands executed on Read the Docs.

Themes depending on this HTML context variable should do something like:

import os
if os.environ.get("READTHEDOCS", False) == "True":
  html_context["READTHEDOCS"] = True

[pradyunsg]

Alrighty, I've filed #795 for giving myself a checking and a singular place to poke y'all about this stuff. :)