Doctr Command Line Help

doctr

doctr

A tool to automatically deploy docs to GitHub pages from Travis CI.

The doctr command is two commands in one. To use, first run:

doctr configure

on your local machine. This will prompt for your GitHub credentials and the name of the repo you want to deploy docs for. This will generate a secure key, which you should insert into your .travis.yml.

Then, on Travis, for the build where you build your docs, add:

- doctr deploy . --built-docs path/to/built/html/

to the end of the build to deploy the docs to GitHub pages. This will only run on the master branch, and won’t run on pull requests.

For more information, see https://drdoctr.github.io/doctr/docs/

usage: doctr [-h] [-V] {deploy,configure} ...

-h, --help

show this help message and exit

-V, --version

show program’s version number and exit

Run –help on the subcommands like ‘doctr deploy –help’ to see the options available.

doctr configure

usage: doctr configure [-h] [--force] [--token] [--no-upload-key]
                       [--no-authenticate] [--key-path KEY_PATH]
                       [--travis-tld {c,com,.com,travis-ci.com,o,org,.org,travis-ci.org}]

-h, --help

show this help message and exit

--force

Run the configure command even if we appear to be on Travis.

--token

Generate a personal access token to push to GitHub. The default is to use a deploy key. WARNING: This will grant read/write access to all the public repositories for the user. This option is not recommended unless you are using a separate GitHub user for deploying.

--no-upload-key

Don’t automatically upload the deploy key to GitHub. To prevent doctr configure from requiring you to login to GitHub, use –no-authenticate.

--no-authenticate

Don’t authenticate with GitHub. This option implies –no-upload-key. This option is also not compatible with private repositories.

--key-path <key_path>

Path to save the encrypted GitHub deploy key. The default is github_deploy_key_+ deploy respository name. The .enc extension is added to the file automatically.

--travis-tld {c,com,.com,travis-ci.com,o,org,.org,travis-ci.org}

Travis tld to use. Should be either ‘.com’ or ‘.org’. The default is to check which the repo is activated on and ask if it is activated on both.

doctr deploy

usage: doctr deploy [-h] [--force | --no-force] [--token | --no-token]
                    [--key-path KEY_PATH] [--built-docs BUILT_DOCS]
                    [--deploy-branch-name DEPLOY_BRANCH_NAME]
                    [--deploy-repo DEPLOY_REPO]
                    [--branch-whitelist [BRANCH [BRANCH ...]]]
                    [--no-require-master | --require-master]
                    [--command COMMAND] [--no-sync | --sync] [--no-temp-dir]
                    [--no-push | --push] [--build-tags | --no-build-tags]
                    [--gh-pages-docs GH_PAGES_DOCS]
                    [--exclude EXCLUDE [EXCLUDE ...]]
                    [deploy_directory]

deploy_directory

Directory to deploy the html documentation to on gh-pages.

-h, --help

show this help message and exit

--force

Run the deploy command even if we do not appear to be on Travis.

--no-force

Inverse of “–force”

--token

Push to GitHub using a personal access token. Use this if you used ‘doctr configure –token’.

--no-token

Inverse of “–token”

--key-path <key_path>

Path of the encrypted GitHub deploy key. The default is github_deploy_key_+ deploy respository name + .enc.

--built-docs <built_docs>

Location of the built html documentation to be deployed to gh-pages. If not specified, Doctr will try to automatically detect build location (right now only works for Sphinx docs).

--deploy-branch-name <deploy_branch_name>

Name of the branch to deploy to (default: ‘master’ for *.github.io and wiki repos, ‘gh-pages’ otherwise)

--deploy-repo <deploy_repo>

Repo to deploy the docs to. By default, it deploys to the repo Doctr is run from.

--branch-whitelist <branch>

Branches to deploy from. Pass no arguments to not build on any branch (typically used in conjunction with –build-tags). Note that you can deploy from every branch with –no-require-master.

--no-require-master

Allow docs to be pushed from a branch other than master

--require-master

Inverse of “–no-require-master”

--command <command>

Command to be run before committing and pushing. This command will be run from the deploy repository/branch. If the command creates additional files that should be deployed, they should be added to the index.

--no-sync

Don’t sync any files. This is generally used in conjunction with the –command flag, for instance, if the command syncs the files for you. Any files you wish to commit should be added to the index.

--sync

Inverse of “–no-sync”

--no-temp-dir

Don’t copy the –built-docs directory to a temporary directory.

--no-push

Run all the steps except the last push step. Useful for debugging

--push

Inverse of “–no-push”

--build-tags

Deploy on tag builds. On a tag build, $TRAVIS_TAG is set to the name of the tag. The default is to not deploy on tag builds. Note that this will still build on a branch, unless –branch-whitelist (with no arguments) is passed.

--no-build-tags

Inverse of “–build-tags”

--gh-pages-docs <gh_pages_docs>

!!DEPRECATED!! Directory to deploy the html documentation to on gh-pages. The default is None. The deploy directory should be passed as the first argument to ‘doctr deploy’. This flag is kept for backwards compatibility.

--exclude <exclude>

Files and directories from –built-docs that are not copied.

Configuration

In addition to command line arguments you can configure doctr using the .travis.yml files. Command line arguments take precedence over the value present in the configuration file.

The configuration parameters available from the .travis.yml file mirror their command line siblings except doubledashes -- and --no- prefix are dropped.

Use a doctr section in your travis.yml file to store your doctr configuration:

- language: python
- script:
    - set -e
    - py.test
    - cd docs
    - make html
    - cd ..
    - doctr deploy .
- doctr:
    - key-path : 'path/to/key/from/repo/root/path.key'
    - deploy-repo : 'myorg/myrepo'

The following options are available from the configuration file and not from the command line:

branches:

A list of regular expression that matches branches on which doctr should still deploy the documentation. For example .*\.x will deploy all branches like 3.x, 4.x …