A standalone script for automated building and deploying of sphinx docs via travis-ci
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!
pip install --user travis-sphinx
export PATH=$HOME/.local/bin:$PATH
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
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
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 --source=other/dir/doc build
after_success:
- travis-sphinx deploy
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
travis-sphinx v1.4.0
Usage: travis-sphinx [options] {actions}
Options:
-h, --help Provide information on script or following action
-s, --source Source directory of sphinx docs, default is docs/source
-o, --outdir Directory to put html docs, default is target/doc/build
-n, --nowarn Do no error on warnings
-b, --branches Comma separated list of branches to build on. Default is =master
-p, --pullrequests Deploy on pull requests (not recommended)
Actions:
build Build sphinx documentation
deploy Deploy sphinx docs to travis branch