Travis Sphinx Auto-Doc

.travis.yml

language: python
python:
  - 3.5
install:
  - pip install sphinx sphinx_rtd_theme
script: make html
after_success:
  - ./push.sh
env:
  global:
    - secure: "PASTE ENCRYPTED RESULT HERE"

README.md

Sphinx and Travis Setup

This assumes that you're setting up a repository with only Sphinx (no code). If you're not doing that, you'll need to modify some stuff here, using your best judgment.

1. First, you'll want to install Sphinx (pip install sphinx) and the Read the Docs theme (pip install sphinx_rtd_theme).
2. Then, go through sphinx-quickstart. You shouldn't need most of the plugins, but enable anything you're interested in.
3. In conf.py, find the line html_theme = 'alabaster' and replace it with html_theme = 'sphinx_rtd_theme'.
4. Edit any Sphinx documentation files you're interested in, then do make html to check that everything runs.
5. Make sure to commit, and add _build to your .gitignore.
6. If you haven't already done so, set up the repository on GitHub, and push!
7. Go to Travis, click the plus button, and flick the switch on your repository.
8. Now, add the above .travis.yml and push.sh files. Make sure to make push.sh executable (chmod u+x push.sh).
9. Also, make sure to update ORG, REPO, and EMAIL in .travis.yml.
10. Go to GitHub, Settings, and then Personal Access Tokens. Generate one that has push access to public repos (you can disable everything else).
11. Make sure you have Ruby and Gem installed. Then, install the Travis gem - gem install travis.
12. In your repository root, do travis encrypt GH_TOKEN=[paste your token here].
13. Put that result in your .travis.yml file, in the secure section I marked out.
14. Commit! (Don't push yet)
15. Now, create a gh-pages branch and clear out your working directory (make sure nothing is uncommitted!).

    $ git checkout --orphan gh-pages
    $ rm -rf *
    

16. Add a .nojekyll file to instruct GitHub Pages not to use Jekyll.

    $ touch .nojekyll
    $ git commit -am "Initial gh-pages commit."
    

17. Send that up to GitHub with git push -u origin gh-pages.
18. Travis should start doing its thing. Voila!

push.sh

#!/usr/bin/env bash
# Push HTML files to gh-pages automatically.

# Fill this out with the correct org/repo
ORG=github
REPO=github
# This probably should match an email for one of your users.
EMAIL=example@example.com

set -e

# Clone the gh-pages branch outside of the repo and cd into it.
cd ..
git clone -b gh-pages "https://$GH_TOKEN@github.com/$ORG/$REPO.git" gh-pages
cd gh-pages

# Update git configuration so I can push.
if [ "$1" != "dry" ]; then
    # Update git config.
    git config user.name "Travis Builder"
    git config user.email "$EMAIL"
fi

# Copy in the HTML.  You may want to change this with your documentation path.
cp -R ../$REPO/_build/html/* ./

# Add and commit changes.
git add -A .
git commit -m "[ci skip] Autodoc commit for $COMMIT."
if [ "$1" != "dry" ]; then
    # -q is very important, otherwise you leak your GH_TOKEN
    git push -q origin gh-pages
fi