Base classes for Builders.

class readthedocs.doc_builder.base.BaseBuilder(build_env, python_env, force=False)

The Base for all Builders. Defines the API for subclasses.

Expects subclasses to define old_artifact_path, which points at the directory where artifacts should be copied from.


Do the actual building of the documentation.


Clean the path where documentation will be built.

create_index(extension=u'md', **__)

Create an index file if it needs it.

docs_dir(docs_dir=None, **__)

Handle creating a custom docs_dir if it doesn’t exist.


An optional step to force a build even when nothing has changed.


Move the generated documentation to its artifact directory.

run(*args, **kwargs)

Proxy run to build environment.


Documentation Builder Environments.

class readthedocs.doc_builder.environments.BuildCommand(command, cwd=None, shell=False, environment=None, combine_output=True, input_data=None, build_env=None, bin_path=None, description=None)

Wrap command execution for execution in build environments.

This wraps subprocess commands with some logic to handle exceptions, logging, and setting up the env for the build command.

This acts a mapping of sorts to the API representation of the readthedocs.builds.models.BuildCommandResult model.

  • command – string or array of command parameters
  • cwd – current working path for the command
  • shell – execute command in shell, default=False
  • environment (dict) – environment variables to add to environment
  • combine_output – combine stdout/stderr, default=True
  • input_data (str) – data to pass in on stdin
  • build_env – build environment to use to execute commands
  • bin_path – binary path to add to PATH resolution
  • description – a more grokable description of the command being run

Flatten command.


Set up subprocess and execute command.

  • cmd_input (str) – input to pass to command in STDIN
  • combine_output – combine STDERR into STDOUT

Save this command and result via the API.

class readthedocs.doc_builder.environments.DockerBuildCommand(command, cwd=None, shell=False, environment=None, combine_output=True, input_data=None, build_env=None, bin_path=None, description=None)

Create a docker container and run a command inside the container.

Build command to execute in docker container


Escape special bash characters in command to wrap in shell.

In order to set the current working path inside a docker container, we need to wrap the command in a shell call manually. Some characters will be interpreted as shell characters without escaping, such as: pip install requests<0.8. This escapes a good majority of those characters.


Execute command in existing Docker container.

  • cmd_input (str) – input to pass to command in STDIN
  • combine_output – combine STDERR into STDOUT
class readthedocs.doc_builder.environments.BuildEnvironment(project=None, version=None, build=None, config=None, record=True, environment=None, update_on_success=True)

Base build environment.

Base class for wrapping command execution for build steps. This provides a context for command execution and reporting, and eventually performs updates on the build object itself, reporting success/failure, as well as failures during the context manager enter and exit.

Any exceptions raised inside this context and handled by the eventual __exit__() method, specifically, inside handle_exception() and update_build(). If the exception is a subclass of :py:cls:`BuildEnvironmentError`, then this error message is added to the build object and is shown to the user as the top-level failure reason for why the build failed. Other exceptions raise a general failure warning on the build.

We only update the build through the API in one of three cases:

  • The build is not done and needs an additional build step to follow
  • The build failed and we should always report this change
  • The build was successful and update_on_success is True
  • project – Project that is being built
  • version – Project version that is being built
  • build – Build instance
  • record – Record status of build object
  • environment – shell environment variables
  • update_on_success – update the build object via API if the build was successful

Is build in finished state.


Is build completed, but has top level failure or failing commands.

handle_exception(exc_type, exc_value, _)

Exception handling for __enter__ and __exit__

This reports on the exception we’re handling and special cases subclasses of BuildEnvironmentException. For BuildEnvironmentWarning, exit this context gracefully, but don’t mark the build as a failure. For all other exception classes, including BuildEnvironmentError, the build will be marked as a failure and the context will be gracefully exited.

run(*cmd, **kwargs)

Shortcut to run command from environment.

run_command_class(cls, cmd, **kwargs)

Run command from this environment.

Use cls to instantiate a command

Parameters:warn_only – Don’t raise an exception on command failure

Is build completed, without top level failures or failing commands.


Record a build by hitting the API.

This step is skipped if we aren’t recording the build. To avoid recording successful builds yet (for instance, running setup commands for the build), set the update_on_success argument to False on environment instantiation.

If there was an error on the build, update the build regardless of whether update_on_success is True or not.

class readthedocs.doc_builder.environments.LocalEnvironment(project=None, version=None, build=None, config=None, record=True, environment=None, update_on_success=True)

Local execution environment.


alias of BuildCommand

class readthedocs.doc_builder.environments.DockerEnvironment(*args, **kwargs)

Docker build environment, uses docker to contain builds.

If settings.DOCKER_ENABLE is true, build documentation inside a docker container, instead of the host system, using this build environment class. The build command creates a docker container from a pre-built image, defined by settings.DOCKER_IMAGE. This container is started with a mount to the project’s build path under user_builds on the host machine, walling off project builds from reading/writing other projects’ data.

Parameters:docker_socket – Override to Docker socket URI

alias of DockerBuildCommand


Return id of container if it is valid.


Get container state.


Create docker container.


Create Docker client connection.


Update buildenv state from container state.

In the case of the parent command exiting before the exec commands finish and the container is destroyed, or in the case of OOM on the container, set a failure state and error message explaining the failure on the buildenv.



Sphinx backend for building docs.

class readthedocs.doc_builder.backends.sphinx.BaseSphinx(*args, **kwargs)

The parent for most sphinx builders.


Modify given file from a whitelisted user’s project.


Get configuration parameters to be rendered into the conf file.

class readthedocs.doc_builder.backends.sphinx.DockerLatexBuildCommand(command, cwd=None, shell=False, environment=None, combine_output=True, input_data=None, build_env=None, bin_path=None, description=None)

Ignore LaTeX exit code if there was file output.

class readthedocs.doc_builder.backends.sphinx.LatexBuildCommand(command, cwd=None, shell=False, environment=None, combine_output=True, input_data=None, build_env=None, bin_path=None, description=None)

Ignore LaTeX exit code if there was file output.

class readthedocs.doc_builder.backends.sphinx.PdfBuilder(*args, **kwargs)

Builder to generate PDF documentation.