Setup sphinx docs to use gh-pages branch

README.rst

@@ -145,6 +145,28 @@ configurations.
     pip install -e '.[test]'
     pytest
 
+Documentation
+^^^^^^^^^^^^^
+
+Documentation is generated using `sphinx <http://www.sphinx-doc.org/>`_.
+To generate documentation, first install development requirements::
+
+    pip install -r dev-requirements.txt
+
+Then build documentation using the customized make file in the `docs`
+directory::
+
+    cd sphinx-docs
+    make html
+
+To build and publish documentation for a release, add the ``gh-pages`` branch
+to the ``docs`` folder in your worktree::
+
+    git worktree add -B gh-pages docs origin/gh-pages
+
+In the ``sphinx-docs`` folder, use ``make docs`` to build the HTML documents
+and static assets, add it to the docs folder, and commit it for publication on
+Github Pages. After the build completes, push to GitHub from the ``docs`` folder.
 
 License
 -------

sphinx-docs/Makefile

@@ -13,15 +13,15 @@ help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
-
+l
 # build production documentation for publishing on github pages
 # run the html build, then move to /docs/ folder and add to git
 docs:
-	rm -rf ../docs
+	rm -rf ../docs/*
 	@make html
-	mv _build/html ../docs
-	git add -f ../docs
-
+	mv html/* ../docs/
+	touch ../docs/.nojekyll
+	cd ../docs && git add --all && git commit -m "Publishing updated documentation on gh-pages" && cd ..
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).