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.
-
-
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 bysettings.DOCKER_IMAGE
. This container is started with a mount to the project’s build path underuser_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 underDEBUG
.The object returned is passed to Docker function
client.create_container
.
-
image_hash
¶ Return the hash of the Docker image.
-
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.
-
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.
-
class
readthedocs.doc_builder.backends.sphinx.
PdfBuilder
(*args, **kwargs)¶ Builder to generate PDF documentation.