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='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)

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)

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.BuildEnvironment(project=None, version=None, build=None, record=True, environment=None)

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 top-level failures.

Parameters:

• 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

done

Is build in finished state

failed

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

successful

Is build completed, without top level failures or failing commands

update_build(state=None)

Record a build by hitting the API

This step is skipped if we aren’t recording the build, or if we don’t want to record successful builds yet (if we are running setup commands for the build)

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

Local execution environment

command_class

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

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

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)

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.