make ghpages to push to gh-pages branch

- `make ghpages` will build the docs in docs/build/html and push it to an
  existing gh-pages branch; especially useful when building on a fork;
  you will have to initialize your gh-pages branch manually and enable
  docs on the gh-pages branch in the repo settings
- ignore build directories (top level build and docs/build)

.gitignore

@@ -11,4 +11,5 @@
 
 # generated files
 docs/build
-docs/source/api/*.rst
+docs/source/api/*.rst
+build/

docs/Makefile

@@ -12,9 +12,27 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile ghpages
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# push to this repo's gh-pages (must be named origin and must have a gh-pages branch)
+
+REPONAME = origin
+
+ghpages: html
+	-(ORIGIN_REMOTE_URL=`git config --get remote.$(REPONAME).url`; \
+	rev=`git rev-parse --short HEAD`; \
+        cd $(BUILDDIR)/$^ \
+	&& git init \
+	&& git remote add origin $${ORIGIN_REMOTE_URL} \
+	&& git fetch --depth 50 origin gh-pages \
+	&& git reset origin/gh-pages \
+	&& touch .nojekyll \
+	&& git add -A . \
+        && git diff-index --quiet HEAD -- || git commit -m "updated sphinx docs from $${rev}" \
+	&& git push -q origin HEAD:gh-pages)
+	rm -rf $(BUILDDIR)/$^/.git