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.

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 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.

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.