A script to build and deploy your Sphinx (http://sphinx-doc.org) documentation. Use it if you have your reStructuredText files in one repo, and your published HTML docs in a separate GitHub pages repo.

publish

#!/bin/bash

# Builds the HTML documentation files from the reStructuredText source,
# then copies the HTML files created by Sphinx, from the 'freeseer-docs' repo
# to the 'freeseer.github.io' repo. Finally, publishes the updated
# documentation by staging the files, commiting, and pushing them.
#
# A one-line commit message for git is an optional argument.
#
# Author(s):
# Dennis Ideler <ideler.dennis at gmail.com>
#
# Copyright 2012-2013  Free and Open Source Software Learning Centre (FOSSLC)
# http://fosslc.org
#
#  This program is free software: you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
# For support, questions, suggestions or any other inquiries, visit:
# http://freeseer.github.io

# Exit on error.
set -o errexit

# Verify all parameters are set.
#set -o nounset

# Remove old content and build the new HTML output.
rm --recursive --dir ./build/html/*
make html

echo "Locating freeseer.github.io repository..."
REPO=$(find $HOME -type d -name freeseer.github.io)

# Exit if not found.
if [ "$REPO" = "" ]; then echo "freeseer.github.io repo not found!"; exit 1; fi

# Keep track of freeseer-docs location.
DOCS="$( cd "$( dirname "$0" )" && pwd )"

# Silently switch to freeseer.github.io, or exit if directory doesn't exist.
pushd "$REPO" >/dev/null || { echo "You don't have the latest revision!"; exit 1; }

echo "Copying docs..."
cp -rp $DOCS/build/html/* .

# Check if the local branch has diverged from the remote branch, abort if so.
if [ `git log --pretty=%H ...refs/heads/master^` != `git ls-remote origin -h refs/heads/master | cut -f1` ]
then
  echo "Your master branch and origin/master have diverged"
  git fetch origin --quiet
  git log HEAD..origin/master --graph --abbrev-commit --date=relative \
    --pretty=format:"%Cred%h%Creset %an: %s - %Creset %C(yellow)%d%Creset %Cgreen(%cr)%Creset"
  echo "***aborted: Please switch to your freeseer.github.io repo and sync it with origin"
  exit 1
fi

echo "Staging and committing changes..."
git add .

# Use custom commit message if provided.
if [ -n "$1" ]; then
  git commit -m "$1"
else
  git commit -m 'Updating docs'
fi

echo "Deploying to GitHub Pages..."
if !(`git push origin master --quiet`)  # May require user's GitHub password.
then
  echo "***error: Changes not deployed to GitHub, push failed"
  exit 1
fi

# Silently switch back to the original directory.
popd >/dev/null
echo "Documentation published!"

To make the script usable for your own project, you'll have to modify some values. But nowadays I recommend putting your Sphinx docs in your codebase repo and using readthedocs.org to build and host them.