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.

This post was updated on Oct 10 to reflect all of the changes to installed dependencies

We are announcing the deprecation of automatic installation of several key project dependencies, and builds will no longer install older documentation tool versions by default.

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.

Starting about a week ago, some users started reporting new errors with their project builds. In most cases, these errors appeared out of nowhere and are usually rather cryptic errors referencing Sphinx and docutils.

So, what is happening?

We are excited to announce that now Read the Docs users can use a newer build specification in their projects that will change the base image to one based on Ubuntu 20.04, ship the recently released Python 3.10, and allow users to easily specify the version of Node.js, Rust, and Go. This feature has been a long time in the making, and we think it will simplify the configuration of many projects.

The Docker images used by our builders were based on Ubuntu 18.04. Recently, we added a new feature to install custom system packages, which allowed many projects to have better control of their build process without having to use conda to manage non-Python dependencies.

We are thrilled to announce that now Read the Docs users can declare custom operating system packages in their project configuration that will get installed in our Ubuntu-based builders using apt. This has been a long awaited feature, and we think it will simplify the configuration of many projects, especially scientific ones.

The Ubuntu images used by our builders contain lots of preinstalled system packages that we ship to all the projects to make the most common use cases possible. This includes compilers, development headers of common libraries, and others.

In the past year, we’ve been having issues when building projects’ documentation using conda. Our build servers were running out of memory and failing projects’ builds. Read the Docs has this memory constraint to avoid misuse of the platform, causing a poor experience for other users.

Our first solution was a dedicated server for these kind of projects. We would manually assign them to this server on user requests. This workaround worked okay, but it involves a bad experience for the user and also us doing a manual step each time. Over time, we hit again the same issue of OOM, even giving all the memory available to one project to build its documentation. After some research, we found that this is a known issue in the conda community and there are some different attempts to fix it (like mamba). Unfortunately, none of them became the standard yet and the problem is still there.