Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Travis Sphinx Auto-Doc
language: python
- 3.5
- pip install sphinx sphinx_rtd_theme
script: make html
- ./

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, 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 files. Make sure to make executable (chmod u+x
  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!
#!/usr/bin/env bash
# Push HTML files to gh-pages automatically.
# Fill this out with the correct org/repo
# This probably should match an email for one of your users.
set -e
# Clone the gh-pages branch outside of the repo and cd into it.
cd ..
git clone -b gh-pages "https://$$ORG/$REPO.git" gh-pages
cd gh-pages
# Update git configuration so I can push.
if [ "$1" != "dry" ]; then
# Update git config.
git config "Travis Builder"
git config "$EMAIL"
# 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

This comment has been minimized.

Copy link

@fredRos fredRos commented Jul 11, 2017

👍 for the .nojekyll. I couldn't figure out why my page had no CSS style when served on github pages. That fixed it!


This comment has been minimized.

Copy link

@ssokolow ssokolow commented Jan 28, 2020

It's now also possible to have Sphinx handle .nojekyll for you with this:

extensions = [
    # ...
    # ...

Source: sphinx.ext.githubpages in the Sphinx manual

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment