Once a project has been imported and a build is triggered, Read the Docs executes specific pre-defined jobs to build the project’s documentation and update the hosted content. This page explains in detail what happens behind the scenes, and an overview of how you can change this process.
Understanding what’s going on¶
Understanding how your content is built helps with debugging the problems that may appear in the process. It also allows you customize the steps of the build process.
The following are the pre-defined jobs executed by Read the Docs:
Checks out project’s code from the URL’s repository defined for this project. It will use
hg clone, etc depending on the version control system you choose.
Installs operating system & system-level dependencies. This includes specific version of languages (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.
Install default common dependencies.
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, and the CDN is purged so the newer version of the documentation is served.
If there are extra steps required to build the documentation, or you need to execute additional commands to integrate with other tools, it’s possible to run user-defined commands and customize the build process.
Every build has limited resources to avoid misuse of the platform. Currently, these build limits are:
15 minutes build time
3GB of memory
2 concurrent builds
We can increase build limits on a per-project basis. Send an email to email@example.com 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.
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 firstname.lastname@example.org.