Sphinx Documentation Activity (rever.activities.sphinx)

Activity for building sphinx documentation. The doc building happens inside of a docker container. However, the sphinx build directory is mounted into $REVER_DIR/sphinx-build, so the built docs are available on the host.

class rever.activities.sphinx.Sphinx

Runs sphinx inside of a container.

Environment variables that modify this activity’s behaviour are:

$SPHINX_DOCS_DIR

str, the directory in the container that is the root of the documentation. This must be an absolute path. Defaults to '$DOCKER_HOME/$PROJECT/docs'.

$SPHINX_HOST_DIR

str, the directory on the host (ie outside of the container to place the built docs in, default '$REVER_DIR/sphinx-build'.

$SPHINX_BUILD_DIR

str, the directory in the container where sphinx will build the docs, default '{docs_dir}/_build'. If '{docs_dir}' is present in the string, then the string will be formated with the value of $SPHINX_DOCS_DIR. Otherwise, enviroment variables will be expanded.

$SPHINX_OPTS

str or list of str, Additional options to provide to the sphinx builders. Default to no extra options.

$SPHINX_PAPER

str, The paper size to use in latex. Maybe '', 'a4', 'letter', or similar. Defaults to an empty string, which disables this option.

$SPHINX_BUILDER

list of str, The build targets that sphinx should construct. This defaults to ['html'].

As a dockerized activity, the docker environment variables affect the execution of the sphinx activity.

Parameters

namestr, optional

Name of the activity.

depsset of str, optional

Set of activities that must be completed before this activity is executed.

funccallable, optional

Function to perform as activity when this activities is executed (called). The default _func method is good enough for most cases.

undocallable, optional

Function to undo this activities behaviour and reset the repo state.

checkcallable, optional

Function to check if the activity can be run sucessfully on the user’s machine, with their credentials, etc. This function should return True if the activity can be run, and False otherwise.

requiresdict or None, optional

A dict of dicts of the following form that specifies the command line utility and import requirements for this activity.

{
    "commands": {"<cli name>": "<package name>", ...}
    "imports": {"<module name>": "<package name>", ...}
}

The top-level keys are both optional, and this will default to an empty dict. The docker command will be automatically added to the commands dict.

descstr, optional

A short description of this activity

imagestr or None, optional

Name of the image to run, defaults to $DOCKER_INSTALL_IMAGE. Environment variables will be expanded when the activity is run.

langstr, optional

Language to execute the body in, default xonsh. This may also be a full path to an executable.

run_argssequence of str, optional

Extra arguments to pass in after the executable but before the main body. Defaults to the standard compile flag '-c'.

codestr or None, optional

The code to execute in the docker container with lang. If this is None, it may be on the instance itself, passed in when the activity is called, or set by entering the activity as a macro context manager. In this last case, the context block is set as the code.

envbool or dict, optional

Environment to use. This has the same meaning as in rever.docker.run_in_container(). Please see that function for more details, default True.

mountslist of dict, optional

Locations to mount in the running container. This has the same meaning as ing run_in_container(). Please see that function for more details, default does not mount anything.

all_kwargs()

Returns all kwargs for this activity.

check()

Calls this activity’s check() function.

check_requirements()

Checks that an activities requirements are actually available.

checker(check)

Decorator that sets the check function for this activity.

clear_kwargs_from_env()

Removes kwarg from the environment, if they exist.

kwargs_from_env()

Obtains possible func() kwarg from the environment.

setup()

Calls this activity’s setup() initialization function.

setupper(setup)

Decorator that sets the setup function for this activity.

undo()

Reverts to the last instance of this activity. This default implementation uses the revision in the log file from the last time that the activity was started. This may be overridden in a subclass.

undoer(undo)

Decorator that sets the undo function for this activity.

property code

Get’s the code to execute in the docker container.

property env_names

Dictionary mapping parameter names to the names of environment varaibles that the activity looks for when it is executed.