gistfile1.sh

# Create a new repo at github called `test`
# On your local machine:
$ cd test
$ git init
Initialized empty Git repository in /Users/bcf/Git/me/test/.git/ 
$ touch README
$ git add .
$ git commit -m 'first commit'

# wire everything up to the remote at github (replace yourName)
$ git remote add origin git@github.com:yourName/test.git
$ git push origin master

# setup the gh-pages branch
$ git symbolic-ref HEAD refs/heads/gh-pages
$ rm .git/index
$ git clean -fdx
$ echo "My GitHub Page" > index.html
$ git add .
$ git commit -a -m "First page commit"
$ git push origin gh-pages

# prepare the git submodule
$ git checkout master

# ENSURE YOU REPLACE:  YourGitUserName
# ENSURE YOU REPLACE:  YourGitProject.git
$ git submodule add -b gh-pages git@github.com:YourGitUserName/YourGitProject.git doc/_build/html
$ git status

# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	new file:   .gitmodules
#	new file:   doc/_build/html
# 

# add the submodule and commit, init the submodule
$ git commit -m "added gh-pages as submodule"
$ git push
$ git submodule init

# the `doc` directory is already created, so:
$ cd doc
$ sphinx-quickstart # select defaults
# add the sphinx files for building html
$ git add .
$ git commit -m 'sphinx files'
$ cd _build/html # you'll notice the branch changes

# create a .nojekyll file so we can use contents of folders prepended with '_'
$ touch .nojekyll
# head back up to the doc directory
cd ../../
# build our html
$ make html

# git status will show that the files in the html submodule should be committed
# head back down to html
$ cd _build/html
$ git status
$ git add .
$ git commit -m 'site generated'
$ git push origin gh-pages
$ cd ../

# update the contents of _build/html in `master`
$ git commit -a -m "bringing built html into project"
$ git push origin master

# If you need to remove the reference to the submodule:
# REMOVE the submodule references from .gitmodules and .git/config, then
$ git rm --cached doc/_build/html