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]
                           [--key-path KEY_PATH]
-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. If you select this option, you will not be prompted for your GitHub credentials, so this option is not compatible with private repositories.

--key-path <key_path>

Path to save the encrypted GitHub deploy key. The default is ‘github_deploy_key’. The .enc extension is added to the file automatically.

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]
                        [--no-require-master | --require-master]
                        [--command COMMAND] [--no-sync | --sync] [--no-temp-dir]
                        [--no-push | --push] [--gh-pages-docs GH_PAGES_DOCS]
                        [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.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 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.

--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. 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”

--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.

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