API

This is the Python API. We recommend that most users use doctr from the command line.

Local

The code that should be run locally

exception doctr.local.AuthenticationFailed

exception doctr.local.GitHubError

doctr.local.GitHub_login(client_id, *, headers=None, scope='repo')

Login to GitHub.

This uses the device authorization flow. client_id should be the client id for your GitHub application. See https://docs.github.com/en/free-pro-team@latest/developers/apps/authorizing-oauth-apps#device-flow.

‘scope’ should be the scope for the access token (‘repo’ by default). See https://docs.github.com/en/free-pro-team@latest/developers/apps/scopes-for-oauth-apps#available-scopes.

Returns an access token.

doctr.local.GitHub_post(data, url, *, headers)

POST the data data to GitHub.

Returns the json response from the server, or raises on error status.

doctr.local.GitHub_raise_for_status(r)

Call instead of r.raise_for_status() for GitHub requests

Checks for common GitHub response issues and prints messages for them.

doctr.local.check_repo_exists(deploy_repo, service='github', *, headers=None, ask=False)

Checks that the repository exists on GitHub.

This should be done before attempting generate a key to deploy to that repo.

Raises RuntimeError if the repo is not valid.

Returns a dictionary with the following keys:

• ‘private’: Indicates whether or not the repo requires authorization to access. Private repos require authorization.

• ‘service’: For service=’travis’, is ‘travis-ci.com’ or ‘travis-ci.org’, depending on which should be used. Otherwise it is just equal to service.

For service=’travis’, if ask=True, it will ask at the command line if both travis-ci.org and travis-ci.com exist. If ask=False, service=’travis’ will check travis-ci.com first and only check travis-ci.org if it doesn’t exist. ask=True does nothing for service=’github’, service=’travis-ci.com’, service=’travis-ci.org’.

doctr.local.delete_GitHub_token(token_id, *, headers)

Delete a temporary GitHub token

doctr.local.encrypt_to_file(contents, filename)

Encrypts contents and writes it to filename.

contents should be a bytes string. filename should end with .enc.

Returns the secret key used for the encryption.

Decrypt the file with doctr.travis.decrypt_file().

doctr.local.encrypt_variable(variable, build_repo, *, tld='.org', public_key=None, travis_token=None, **login_kwargs)

Encrypt an environment variable for build_repo for Travis

variable should be a bytes object, of the form b'ENV=value'.

build_repo is the repo that doctr deploy will be run from. It should be like ‘drdoctr/doctr’.

tld should be '.org' for travis-ci.org and '.com' for travis-ci.com.

public_key should be a pem format public key, obtained from Travis if not provided.

If the repo is private, travis_token should be as returned by get_temporary_token(**login_kwargs). A token being present automatically implies tld='.com'.

doctr.local.generate_GitHub_token(*, note='Doctr token for pushing to gh-pages from Travis', scopes=None, **login_kwargs)

Generate a GitHub token for pushing from Travis

The scope requested is public_repo.

If no password or OTP are provided, they will be requested from the command line.

The token created here can be revoked at https://github.com/settings/tokens.

doctr.local.generate_ssh_key()

Generates an SSH deploy public and private key.

Returns (private key, public key), a tuple of byte strings.

doctr.local.get_travis_token(*, GitHub_token=None, **login_kwargs)

Generate a temporary token for authenticating with Travis

The GitHub token can be passed in to the GitHub_token keyword argument. If no token is passed in, a GitHub token is generated temporarily, and then immediately deleted.

This is needed to activate a private repo

Returns the secret token. It should be added to the headers like

headers[‘Authorization’] = “token {}”.format(token)

doctr.local.guess_github_repo()

Guesses the github repo for the current directory

Returns False if no guess can be made.

doctr.local.upload_GitHub_deploy_key(deploy_repo, ssh_key, *, read_only=False, title='Doctr deploy key for pushing to gh-pages from Travis', **login_kwargs)

Uploads a GitHub deploy key to deploy_repo.

If read_only=True, the deploy_key will not be able to write to the repo.

Travis

The code that should be run on Travis

doctr.travis.checkout_deploy_branch(deploy_branch, canpush=True)

Checkout the deploy branch, creating it if it doesn’t exist.

doctr.travis.commit_docs(*, added, removed)

Commit the docs to the current branch

Assumes that setup_GitHub_push(), which sets up the doctr_remote remote, has been run.

Returns True if changes were committed and False if no changes were committed.

doctr.travis.copy_to_tmp(source)

Copies source to a temporary directory, and returns the copied location.

If source is a file, the copied location is also a file.

doctr.travis.create_deploy_branch(deploy_branch, push=True)

If there is no remote branch with name specified in deploy_branch, create one.

Note that default deploy_branch is gh-pages for regular repos and master for github.io repos.

Return True if deploy_branch was created, False if not.

doctr.travis.decrypt_file(file, key)

Decrypts the file file.

The encrypted file is assumed to end with the .enc extension. The decrypted file is saved to the same location without the .enc extension.

The permissions on the decrypted file are automatically set to 0o600.

See also doctr.local.encrypt_file().

doctr.travis.deploy_branch_exists(deploy_branch)

Check if there is a remote branch with name specified in deploy_branch.

Note that default deploy_branch is gh-pages for regular repos and master for github.io repos.

This isn’t completely robust. If there are multiple remotes and you have a deploy_branch branch on the non-default remote, this won’t see it.

doctr.travis.determine_push_rights(*, branch_whitelist, TRAVIS_BRANCH, TRAVIS_PULL_REQUEST, TRAVIS_TAG, build_tags, fork)

Check if Travis is running on master (or a whitelisted branch) to determine if we can/should push the docs to the deploy repo

doctr.travis.find_sphinx_build_dir()

Find build subfolder within sphinx docs directory.

This is called by commit_docs() if keyword arg built_docs is not specified on the command line.

doctr.travis.get_current_repo()

Get the GitHub repo name for the current directory.

Assumes that the repo is in the origin remote.

doctr.travis.get_token()

Get the encrypted GitHub token in Travis.

Make sure the contents this variable do not leak. The run() function will remove this from the output, so always use it.

doctr.travis.get_travis_branch()

Get the name of the branch that the PR is from.

Note that this is not simply $TRAVIS_BRANCH. the push build will use the correct branch (the branch that the PR is from) but the pr build will use the _target_ of the PR (usually master). So instead, we ask for $TRAVIS_PULL_REQUEST_BRANCH if it’s a PR build, and $TRAVIS_BRANCH if it’s a push build.

doctr.travis.is_subdir(a, b)

Return true if a is a subdirectory of b

doctr.travis.last_commit_by_doctr()

Check whether the author of HEAD is doctr to avoid starting an infinite loop

doctr.travis.push_docs(deploy_branch='gh-pages', retries=5)

Push the changes to the branch named deploy_branch.

Assumes that setup_GitHub_push() has been run and returned True, and that commit_docs() has been run. Does not push anything if no changes were made.

doctr.travis.run(args, shell=False, exit=True)

Run the command args.

Automatically hides the secret GitHub token from the output.

If shell=False (recommended for most commands), args should be a list of strings. If shell=True, args should be a string of the command to run.

If exit=True, it exits on nonzero returncode. Otherwise it returns the returncode.

doctr.travis.set_git_user_email()

Set global user and email for git user if not already present on system

doctr.travis.setup_GitHub_push(deploy_repo, *, auth_type='deploy_key', full_key_path='github_deploy_key.enc', require_master=None, branch_whitelist=None, deploy_branch='gh-pages', env_name='DOCTR_DEPLOY_ENCRYPTION_KEY', build_tags=False)

Setup the remote to push to GitHub (to be run on Travis).

auth_type should be either 'deploy_key' or 'token'.

For auth_type='token', this sets up the remote with the token and checks out the gh-pages branch. The token to push to GitHub is assumed to be in the GH_TOKEN environment variable.

For auth_type='deploy_key', this sets up the remote with ssh access.

doctr.travis.setup_deploy_key(keypath='github_deploy_key', key_ext='.enc', env_name='DOCTR_DEPLOY_ENCRYPTION_KEY')

Decrypts the deploy key and configures it with ssh

The key is assumed to be encrypted as keypath + key_ext, and the encryption key is assumed to be set in the environment variable env_name. If env_name is not set, it falls back to DOCTR_DEPLOY_ENCRYPTION_KEY for backwards compatibility.

If keypath + key_ext does not exist, it falls back to github_deploy_key.enc for backwards compatibility.

doctr.travis.sync_from_log(src, dst, log_file, exclude=())

Sync the files in src to dst.

The files that are synced are logged to log_file. If log_file exists, the files in log_file are removed first.

Returns (added, removed), where added is a list of all files synced from src (even if it already existed in dst), and removed is every file from log_file that was removed from dst because it wasn’t in src. added also includes the log file.

exclude may be a list of paths from src that should be ignored. Such paths are neither added nor removed, even if they are in the logfile.