readthedocs.doc_builder

readthedocs.doc_builder.base

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.

build()

Do the actual building of the documentation.

clean(**__)

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.

force(**__)

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

move(**__)

Move the generated documentation to its artifact directory.

run(*args, **kwargs)

Proxy run to build environment.

readthedocs.doc_builder.environments

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, record_as_success=False)

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.

Parameters:
  • 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
get_command()

Flatten command.

run()

Set up subprocess and execute command.

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

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, record_as_success=False)

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

Build command to execute in docker container

get_wrapped_command()

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.

run()

Execute command in existing Docker container.

Parameters:
  • cmd_input (str) – input to pass to command in STDIN
  • combine_output – combine STDERR into STDOUT
class readthedocs.doc_builder.environments.LocalEnvironment(project, environment=None)
command_class

alias of BuildCommand

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

Local execution build environment.

command_class

alias of BuildCommand

class readthedocs.doc_builder.environments.DockerBuildEnvironment(*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
command_class

alias of DockerBuildCommand

container_id

Return id of container if it is valid.

container_state()

Get container state.

create_container()

Create docker container.

get_client()

Create Docker client connection.

get_container_host_config()

Create the host_config settings for the container.

It mainly generates the proper path bindings between the Docker container and the Host by mounting them with the proper permissions. Besides, it mounts the GLOBAL_PIP_CACHE if it’s set and we are under DEBUG.

The object returned is passed to Docker function client.create_container.

update_build_from_container_state()

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.

readthedocs.doc_builder.backends

readthedocs.doc_builder.backends.sphinx

Sphinx backend for building docs.

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

The parent for most sphinx builders.

append_conf(**__)

Modify given conf.py file from a whitelisted user’s project.

get_config_params()

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, record_as_success=False)

Ignore LaTeX exit code if there was file output.

run()

Execute command in existing Docker container.

Parameters:
  • cmd_input (str) – input to pass to command in STDIN
  • combine_output – combine STDERR into STDOUT
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, record_as_success=False)

Ignore LaTeX exit code if there was file output.

run()

Set up subprocess and execute command.

Parameters:
  • cmd_input (str) – input to pass to command in STDIN
  • combine_output – combine STDERR into STDOUT
class readthedocs.doc_builder.backends.sphinx.PdfBuilder(*args, **kwargs)

Builder to generate PDF documentation.