We are announcing the deprecation of building without a configuration file (.readtehdocs.yaml) together with the deprecation of configuration file v1 as well.

Read the Docs will soon start requiring a .readthedocs.yaml configuration file for all projects in order to build documentation successfully. We will stop creating a default configuration file behind the scenes, making assumptions for your projects, and automatically fixing problems with project configurations.

We are happy to announce a new beta feature that allows users to override the Read the Docs build process completely. We previously talked about executing custom commands in-between the Read the Docs build process. That approach is not sufficient for projects with a heavily customized build process, or those that want to use a different documentation tool like Pelican, Docsify and Docusaurus for their documentation. Some of which were not able to use our platform at all. Until now! We have good news for them!

The new configuration file option build.commands allows projects to only execute exactly the commands they want. No more. No less. This means that Read the Docs won’t execute any of the default commands behind the scenes. You have 100% control over the build process.

Read the Docs allows you to keep your documentation up to date in a simple way, by triggering a new build each time developers push a git repository. Depending on your workflow, there could be situations where multiple pushes are done during a short time window. This causes a situation where you have to wait a long time for a build that will be immediately overwritten.

To avoid waiting for those builds to be executed, we implemented a new feature to cancel these useless builds and only execute the latest one. This considerably improves the user experience and also reduces resource costs and energy waste.

Read the Docs generates a lot of data. We are the largest documentation platform out there, with hundreds of thousands of projects using our product every day to host their documentation. This data includes simple things like number of users, builds using a particular Docker image, as well as more interesting ones like pageviews or Python dependencies installed via a requirements.txt file. We didn’t collect this data in a systemic way during the first 10 years of our existence.

Last year, with the growth of our product and the team, plus the CZI grant we received, we started asking ourselves some questions that we couldn’t answer with the data we had. We decided to start working on a project to collect relevant data to answer a large number of questions about how people use our service.

We are happy to announce a new feature to specify user-defined build jobs on Read the Docs. If your project requires custom commands to be run in the middle of the build process, they can now be executed with the new config key build.jobs. This opens up a complete world full of new and exciting possibilities to our users.

If your project has ever required a custom command to run during the build process, you probably wished you could easily specify this. You might have used a hacky solution inside your Sphinx’s conf.py file, but this was not a great solution to this problem.

We are excited to announce that our API v3 has reached a stable release, and is now available for all Read the Docs users. Since we announced the API v3 beta, we have been adding extra functionality and bug-fixing minor issues based on user feedback.

The new API v3 is not a fully replacement (yet!) of API v2, but we highly recommend using API v3 for all the new integrations. API v2 will be deprecated soon, though we don’t have a firm timeline for deprecation. We will alert users with our plans when we do.

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.

In the last months, we have been working on making our API better. Considering the limitations of our current REST API v2, we decided to make a bigger step forward and create a new API v3, putting the focus on the use cases we heard about from existing users.

Compared to API v2, our new API v3 has some big differences that make it more user-friendly and useful.