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 asking for your GitHub credentials, 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”
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.
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 like3.x
,4.x
…