Automating documentation workflow with sphinx and github pages

I’ve got a large and growing list of open source projects I try to keep up to date. Some are better documented than others, but I’m working on making them all very simple to get started with. In light of that, I’ve done some hacking around on how to get the workflow of github pages and sphinx nailed down.

For a while I was manually building the docs in the master branch, copying the html out to a temp directory, then switching to the gh-pages branch and pasting it all in there. As annoying as that was, it didn’t happen that often.

Today it was time to automate that, so I did some googling around, and found a few good resources, notably here. I wanted to take it one step further though, so I’ve added a bash script to categorical encoding, which does it all (note that this should only be run with your repo as the working directory):

#!/usr/bin/env bash

# build the docs
cd docs
make clean
make html
cd ..

# commit and push
git add -A
git commit -m "building and pushing docs"
git push origin master

# switch branches and pull the data we want
git checkout gh-pages
rm -rf .
touch .nojekyll
git checkout master docs/build/html
mv ./docs/build/html/* ./
rm -rf ./docs
git add -A
git commit -m "publishing updated docs..."
git push origin gh-pages

# switch back
git checkout master

It’s pretty simple. In fact, simple enough that I’m not sure why it took me so long to do it. But basically if you’ve setup sphinx docs in a directory called “docs” and the output gets put in docs/build/html, then just make sure that you have a gh-pages branch and that you haven’t git-ignored your html, and this will build the docs and deploy them in one simple call.