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.

Note

All the steps are run inside a Docker container, using the image defined in build.os. The build has access to all pre-defined environment variables and custom environment variables.

The build process includes the following jobs:

checkout:

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.

system_dependencies:

Installs operating system and runtime dependencies. This includes specific versions of a language (e.g. Python, Node.js, Go, Rust) and also apt packages.

build.tools can be used to define a language version, and build.apt_packages to define apt packages.

create_environment:

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:

Install default and project dependencies. This includes any requirements you have configured in Requirements file.

If the project has extra Python requirements, python.install can be used to specify them.

Tip

We strongly recommend pinning all the versions required to build the documentation to avoid unexpected build errors.

build:

Runs the main command to build the documentation for each of the formats declared (formats). It will use Sphinx (sphinx) or MkDocs (mkdocs) depending on the project.

upload:

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.

Cancelling builds

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:

Manually:

Once a build was triggered, project administrators can go to the build detail page and click Cancel build.

Automatically:

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.

Programatically:

You can use user-defined commands on build.jobs or build.commands (see Build process customization) to check for your own cancellation condition and then return exit code 183 to cancel a build. You can exit with the code 0 to 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.

Tip

Take a look at Cancel build based on a condition section for some examples.

Build resources

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 support@readthedocs.com.