doc_builder

doc_builder.base

class doc_builder.base.BaseBuilder(version, 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(id=None, **kwargs)

Do the actual building of the documentation.

clean(**kwargs)

Clean the path where documentation will be built

create_index(extension='md', **kwargs)

Create an index file if it needs it.

docs_dir(docs_dir=None, **kwargs)

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

force(**kwargs)

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

move(**kwargs)

Move the documentation from it’s generated place to its artifact directory.

doc_builder.envrionments

Documentation Builder Environments

class doc_builder.environments.BuildCommand(command, cwd=None, shell=True, environment=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.

Parameters:
  • command – string or array of command parameters
  • cwd – current working path
  • shell – execute command in shell, default=True
  • environment – environment variables to add to environment
get_command()

Flatten command

run(cmd_input=None, combine_output=False)

Set up subprocess and execute command

Parameters:
  • cmd_input (str) – input to pass to command in STDIN
  • combine_output – combine STDERR into STDOUT
class doc_builder.environments.DockerBuildCommand(command, image=None, mounts=None, name=None, remove=True, user=None, environment=None, **kwargs)

Create a docker container and run a command inside the container

Build command to execute in docker container

Parameters:
  • command – Command to run as a string or a lists of strings to be joined as space-separated.
  • image – Docker image to run a container from. This is set in settings as well
  • mounts – List of tuples defining pairs of paths to be mounted, the first element should be the host path, the second should be the container’s path.
  • user – User to run command as
  • name – Container name
  • remove – Automatically remove container after container command exits
class doc_builder.environments.DockerEnvironment(version)

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:version – Project version to be building
build()

Run build command in container

This serializes the version object into JSON, which is passed through Docker, into readthedocs.core.management.commands.run_docker. This management command reads the JSON on STDIN, and builds a mocked up version object to pass around the build process. After the build process, JSON is output on STDOUT and read by this command, converting it back into a results dictionary.

We also set environment settings to pass into the docker command, for overriding settings in the subprocess django instance inside the container.

Note

This is a temporary hack. We shouldn’t need to pass JSON back and forth, but cutting off all access to API and Celery is a necessary part of containing builds. In the future, builds should happen in a contained environment like LXC or Docker containers, but this code should managed build state outside the process, eliminating the need for IPC of any kind.

container_id()

Container ID used in creating and destroying docker images

env_settings()

Return local django settings as environment variables

This is used when passing in env variables to the subprocess management command, instead of requiring docker containers have a settings file installed with each build of the docker image.

Warning

Never, ever, pass secure data as an evironment variable.

class doc_builder.environments.EnvironmentBase(version)

Base build environment

Placeholder for reorganizing command execution.

Parameters:version – Project version that is being built
response(cmd, step='doc_builder')

Render a response for reporting to the build command page

Parameters:
  • cmd – BuildCommand instance after executing run, or dict containing the same keys to mock a cmd response.
  • step – Result step for output page

Note

In the future, this should return an actual object, or handle organizing command return to the API on a per-command basis.

doc_builder.backends

doc_builder.backends.sphinx

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

The parent for most sphinx builders.

append_conf(**kwargs)

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