travis-sphinx
A standalone script for automated building and deploying of sphinx docs via travis-ci
What does it do?
travis-sphinx aims to take the hassle out of building and pushing docs to your gh-pages. deploying to your github page can be tedious especially when you're making many small changes overtime or even just making a minor revision you'd like to see live; travis-sphinx will automate your build and deploy process with the help of travis-ci!
Check out cadquery for a live example of travis-sphinx in action!
Installation
pip install --user travis-sphinx
export PATH=$HOME/.local/bin:$PATH
Getting Started
If you aren't already familiar with travis-ci, take a look at their getting-started guide. Otherwise the steps below will outline how to get travis-sphinx running in your repository
The first step you'll need to do is simply make sure you have a gh-pages branch that exists, if it doesn't:
git checkout -b gh-pages
git rm -rf .
git push --set-upstream origin gh-pages
Obtaining a Personal Access Token
travis-sphinx requires a personal access token to be able to push changes to gh-pages, so you'll need to generate a token to use. Head over to your github account settings:
To generate a token: go to personal access tokens and click generate new token. Make sure to copy this to your clipboard for the next step!
The easiest way to set this token is to head over to https://travis-ci.org/ and click on settings for the repository you'll be using travis-sphinx with. You can add the token by specifying it in the enviroment variable under the name GH_TOKEN. You can also follow this tutorial on giving travis permissions, but the first options is much more simple
Now travis-sphinx can push to your gh-pages, all done! The next step is calling travis-sphinx within your .travis.yml
Calling travis-sphinx
Once your personal access token is setup, you can begin using travis-sphinx within your configuration file. The two calls that should be used are:
script:
- travis-sphinx build
after_success:
- travis-sphinx deploy
build will generate the actual documentation files while deploy will move those files to gh-pages. If you don't have your documentation in the standard docs/source path, you can specify where they are with --source. This tool also assumes that you would like to build and deploy the master branch and any tags pushed. If you would like to point the tool elsewhere, this can be solved using --branches , e.g. travis-sphinx --branches=test,production will build and deploy on only the test and production branches.
script:
- travis-sphinx build --source=other/dir/doc
after_success:
- travis-sphinx deploy
Specifying a Custom Deploy Repository
Per #38, you can now specify a custom deployment repository if you're using a fork for working on documentation. To do so, under your travis environment variables, using the following constant:
GH_REPO_SLUG = 'syntaf/fork-of-my-repo'
Example Configuration
note: See this repositories .travis.yml for a simpler configuration script. The below script is for conda environments which have a number of dependencies that also need to be installed.
language: python - "2.7"
# before_install will simply setup a conda enviroment for installing python packages, if you
# have project dependencies it's usually recommended to go this route
before_install:
- wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh
- chmod +x miniconda.sh
- "./miniconda.sh -b"
- export PATH=/home/travis/miniconda2/bin:$PATH
- conda update --yes conda
- sudo rm -rf /dev/shm
- sudo ln -s /run/shm /dev/shm
install:
- conda install --yes python="2.7" sphinx
- pip install --user travis-sphinx
script:
- travis-sphinx build
after_success:
- travis-sphinx deploy
Also see a working example at the dnppy repository
Help
Usage: travis-sphinx [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
-v, --verbose
-o, --outdir DIRECTORY Directory to put html docs, default is target
[default: doc/build]
--help Show this message and exit.
Commands:
build Build sphinx documentation.
deploy Deploy sphinx docs to gh_pages branch by...
Usage: travis-sphinx build [OPTIONS]
Build sphinx documentation.
Options:
-s, --source DIRECTORY Source directory of sphinx docs [default:
doc/source]
-n, --nowarn BOOLEAN Do not error on warnings
--help Show this message and exit.
Usage: travis-sphinx deploy [OPTIONS]
Deploy sphinx docs to gh_pages branch by pulling from output dir.
Options:
-b, --branches TEXT Comma separated list of branches to build on
[default: master]
-c, --cname TEXT Write a CNAME file with the given CNAME.
-m, --message TEXT The commit message to use on the target branch.
[default: Update documentation]
-x, --deploy-host TEXT Specify a custom domain for GitHub, useful for
enterprise domains. [default: github.com]
--help Show this message and exit.