Read the Docs Blog - Posts from Barcelona, Spain

API v3 is now stable

2021-02-16T00:00:00Z

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.

New features

We’re excited about the following actions that API v3 makes possible:

Import new projects
Activate a version
Trigger builds
Check build status
Manage redirects

API v3 allows you to easily manage common tasks on your Read the Docs project and organization. These include:

Setting up documentation for a new project
Automating the release of a new version
Pausing a release if you detect a failed build
Automatically create redirects for changes files

If you want to know more about it, please check out the full APIv3 documentation.

Help us make it better

We always love to hear from users about how they are using the API. We want to help you manage your documentation in the easiest and most efficient way possible. Please, feel free to open an issue in our issue tracker if there is a use case we are not covering.

Better support for scientific project documentation

2020-04-28T00:00:00Z

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.

Meanwhile, in another completely different set of work, we were migrating all of our infrastructure to a different architecture:

Azure Virtual machine scale sets for autoscaling our servers,
Azure storage accounts to store all the user’s documentation
Proxito, an internal service to remove a lot of the state from our servers (more about this migration coming in a future post)

This helped us to reduce costs and allowed us to spin up bigger instances for the builders. We have also made some other important operational changes:

Our builders are now single-process, giving all the memory available to only one project without worrying about affecting others.
We added custom task router that routes small builds to small servers (3GB RAM), and big builds to larger servers (7GB RAM). This removes the need for users to ask us to upgrade their isntances.
Assigned all conda projects to be built by big servers by default.

If you ever had a memory issue on Read the Docs, we’d appreciate if you give it a try again. Please let us know about your experience when building scientific documentation. If you know that any of your friends were hitting this issue in the past, we encourage you to talk to them and tell them to give it a try.

We are excited to have more scientific documentation on our platform and we are doing our small part to make this happen and have better science in the world.

Announcing API v3 Beta

2019-08-27T00:00:00Z

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.

These differences includes:

API access requires authentication
Token based API authentication
Read and write
Resource lookup can use project’s slug
Wider resource coverage

Some examples of new queries and actions that will be possible with the API are:

If you want to know more about it, please check out the full APIv3 documentation.

Invite-only beta feature

APIv3 is currently in an invite-only beta state on our community site, https://readthedocs.org. In case you want to test it and give us feedback on it, please email us to get early access.

Based on the feedback we receive from you, we plan to add more features to cover most of the common use cases. Please, help us with your feedback to make the new APIv3 even better!