Build process overview
Once a project has been imported and a build is triggered, Read the Docs executes a set of pre-defined jobs to build and upload documentation. This page explains in detail what happens behind the scenes, and includes an overview of how you can change this process.
Understanding the build process
Understanding how your content is built helps with debugging any problems you might hit. It also gives you the knowledge to customize the build process.
The build process includes the following jobs:
Checks out a project’s code from the repository URL. On Read the Docs for Business, this environment includes the SSH deploy key that gives access to the repository.
Installs operating system and runtime dependencies. This includes specific versions of a language (e.g. Python, Node.js, Go, Rust) and also
Creates a Python environment to install all the dependencies in an isolated and reproducible way. Depending on what’s defined by the project, a virtualenv or a conda environment (conda) will be used.
If the project has extra Python requirements, python.install can be used to specify them.
We strongly recommend pinning all the versions required to build the documentation to avoid unexpected build errors.
Once the build process finishes successfully, the resulting artifacts are uploaded to our servers. Our CDN is then purged so your docs are always up to date.
If you require additional build steps or customization, it’s possible to run user-defined commands and customize the build process.
There may be situations where you want to cancel a running build. Cancelling builds allows your team to speed up review times and also help us reduce server costs and our environmental footprint.
A couple common reasons you might want to cancel builds are:
the build has an external dependency that hasn’t been updated
there were no changes on the documentation files
For these scenarios, Read the Docs supports three different mechanisms to cancel a running build:
Once a build was triggered, project administrators can go to the build detail page and click Cancel build.
When Read the Docs detects a push to a version that is already building, it cancels the running build and starts a new build using the latest commit.
You can use user-defined commands on
build.commands(see Build process customization) to check for your own cancellation condition and then return exit code
183to cancel a build. You can exit with the code
0to continue running the build.
When this happens, Read the Docs will notify your Git platform (GitHub/GitLab) that the build succeeded (✅), so the pull request doesn’t have any failing checks.
Take a look at Cancel build based on a condition section for some examples.
Every build has limited resources assigned to it. Generally, Read the Docs for Business users get double the build resources, with the option to increase that.
Our build limits are:
30 minutes build time
7GB of memory
Concurrent builds vary based on your pricing plan
If you are having trouble with your documentation builds, you can reach our support at email@example.com.
15 minutes build time
3GB of memory
2 concurrent builds
We can increase build limits on a per-project basis. Send an email to firstname.lastname@example.org providing a good reason why your documentation needs more resources.
If your business is hitting build limits hosting documentation on Read the Docs, please consider Read the Docs for Business which has much higher build resources.