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!

• Installation
• Getting Started
  • Obtaining a personal access token
  • Calling travis-sphinx
  • Custom repository deployment
• Example
• Help

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.