🚀 We started testing a new flyout menu as part of our beta test for documentation addons. The beta test is currently limited to projects using the build.commands configuration key.

🛣️ We continue to have a number deprecations in progress. We announced this month deprecations of installing using system packages, the configuration key build.image, and installation of pinned versions of Sphinx and MkDocs. Keep an eye on your email for any deprecation notifications, as we will continue to notify maintainers of projects that might be impacted.

We are happy to announce that a new flyout menu is now available as part of the ongoing beta test for our latest project, Read the Docs Addons.

After much hard work, we are excited to begin testing this feature with more projects. We have previously been testing other documentation features as part of this ongoing beta, but the flyout menu is by far the most prominent feature yet.

We are announcing the deprecation of building with older documentation tool versions by default.

Historically, Read the Docs installed a specific version based on the date your project was created. This caused odd issues where reimporting a project could change behavior, and caused users to continue using very old versions of build tools that weren’t supported by their authors. This was done to maintain backwards compatibility, but our platform now has robust support for defining a build environment, so we encourage you to pin your dependencies instead.

We are announcing the deprecation of build.image config key in favor of build.os. Read the Docs will start requiring a build.os config key for all projects in order to build documentation successfully. We will start failing builds for projects not using “build.os” in their config file on October 16, 2023.

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

Read the Docs used to pre-install common scientific Python packages like scipy, numpy, pandas, matplotlib and others at system level to speed up the build process. However, with all the work done in the Python ecosystem and the introduction of “wheels”, these packages are a lot easier to install via pip install and these pre-installed packages are not required anymore. If you have Apt package dependencies, they can be installed with build.apt_packages.

With the introduction of our new “Ubuntu 20.04” and “Ubuntu 22.04” Docker images, we stopped pre-installing these extra Python packages and we encouraged users to install and pin all their dependencies using a requirements.txt file. We have already stopped supporting “use system packages” on these newer images.

🏝️ A few team members took vacations this month, and everything kept running smoothly, which is always wonderful to see.

⏩ Our git cloning code was refactored, and now projects should be building much faster. The more git branches and tags you have, the faster the build will be.

Historically, Read the Docs has created an auto-generated index.html file with minimal instructions about how to setup the project correctly when your build didn’t output this file. This auto-generated file has confused more users than it has helped because the behavior on Read the Docs was different from the behavior on their local environment.

To better onboard users, we have deprecated the auto-creation of index.html files on Read the Docs projects. We will now check for an index.html file at the end of the build, and fail it with a clear message of the problem if there is no index.html file in the top level of your output directory.

Historically Read the Docs has created a conf.py file for Sphinx projects and a mkdocs.yml file for MkDocs projects that don’t provide one, to make onboarding easier. This has been confusing a lot our users in different ways and we will remove the auto-creation of a default Sphinx/MkDocs configuration file for projects that don’t have one on August 28th. To avoid unexpected behavior or your documentation builds failing, you should add a configuration file to your project by this date.

The auto-creation of a default configuration file will be completely removed on August 28th. Add a conf.py/mkdocs.yml to your projects before this date to avoid unexpected build failures.

Starting on July 18, 2023 PyPy3 will be removed as an option to build documentation on Read the Docs.

This feature was introduced as an alternative to make Sphinx build faster. However, we found there are no projects building their documentation with PyPy3 and we decided to remove its support to simplify our product and reduce development maintanence.

Starting on August 7, 2023 all new projects imported on Read the Docs will install only sphinx, mkdocs and readthedocs-sphinx-ext as “core requirements”. The default behavior will be to install the latest version of these requirements.

Note that previously Read the Docs was installing also jinja, sphinx-rtd-theme, pillow, mock, alabaster, commonmark and recommonmark specifying particular versions depending on different factors that were confusing for users and hard to debug.

🚀 We shipped support for customizing the URL path for projects and subprojects, allowing you to remove or customize the /projects/ path on subprojects. This is enabled via Support request currently, and only on certain plans on Read the Docs for Business.

🛣️ Deprecations underway: We have a number of old feature deprecations underway. The goal here is to reduce complexity of our build platform, and enable users to control their own builds via build.tools and build.commands instead of feature flags. Keep an eye on your email for any deprecation notifications that might impact your project.

⚠️ A .readthedocs.yaml configuration file will be required for your future builds. Read more about this change in Migrate your project to .readthedocs.yaml configuration file v2.

✅️ Visiting a language slug of a project without specifying the version now redirects to the default version. For instance, /en/ redirects to /en/latest/.

We are announcing a new requirement for all builds to use our configuration file version 2. This announcement deprecates builds without a configuration file, as well as version 1 of our configuration file.

Read the Docs will start requiring a .readthedocs.yaml configuration file for all projects in order to build documentation successfully. We will stop supporting builds without explicit configuration, because this creates implicit dependencies that users aren’t aware of. We plan to start failing builds not using configuration file version 2 on September 25, 2023.

🚁️ The proxy application El Proxito has been rewritten. El Proxito resolves URLs for all documentation websites hosted on Read the Docs. The new rewrite improves the performance of the resolver and makes it possible to add planned features.

🔎️ …One of the new features available in the new El Proxito implementation, is an improved 404 page (see the screenshot below). The new 404 page is contextualized and contains better error messages and tips for users and project owners. We are gradually rolling out the new El Proxito while monitoring its stability, and users will experience new features only on projects where it has been enabled.

📚️ Over the past ~6 months, we gradually refactored our user documentation to align with the Diátaxis Framework. The results are now manifested in the structure of the navigation sidebar and the landing page on docs.readthedocs.io.

📊️ All of our websites now use Plausible for analytics.

Read the Docs is in the process of migrating our primary marketing website to a single site: https://about.readthedocs.com. The new site offers users more information about our products and their features, in a combined presentation of what was previously divided between two websites (Read the Docs Community (readthedocs.org) and Read the Docs for Business (readthedocs.com)). The new site will also serve as a single entrypoint for users that are logging in to Read the Docs accounts. There has been a good deal of confusion around our two sites, and this change makes it more clear which site you’re going to.

Importantly, we are keeping both our Community and Business sites separate for logged in users. There are no changes in our commitment to offering free hosting for open source, or the separation of infrastructure for Business customers.

⭐️ We passed our 10,000th issue/pull request on GitHub. And it’s pretty much an equal split between the 5039 issues and 4872 pull requests now registered. Thanks to the whole community for building this together through code, issues, suggestions… and documentation!

🌪️ Follow up: Build times have gone rapidly down after last month’s introduction of parallel uploading of artifacts with rclone. Depending on the number of files in your build output, build times may have gone down several seconds or several minutes. For instance, a large project like Write the Docs has gone down from ~7 minutes to under 3 minutes. If you want to see the change for your project, have a look at your build times before and after February 8.

Here are the latest updates from our team since the previous newsletter:

🪄️ Build outputs are now stored in a well-known location: _readthedocs/<format>. This opens up many new and exciting possibilities for generating and processing final output formats, which we will uncover in an upcoming blog post. PDFs for MkDocs and encrypted documentation are just two demos that we have ready. Stay tuned!

Happy 2023!

Here are the latest updates from our team since the previous newsletter:

Important updates to this post ⬇️

sphinx-rtd-theme 1.2.0 has been released with support for Sphinx 6.