Generalize the Makefile and improve instructions

Makefile

@@ -1,26 +1,24 @@
 # Makefile for Sphinx documentation
 #
-
-GH_SOURCE_DIRS = source 
-GH_BUILT_DIRS = _images _sources people projects papers 
-GH_BUILT_FILES = index.html
-
-GH_SOURCE_BRANCH = source
-GH_BUILD_BRANCH = master
-GH_CYCLUS_REMOTE = upstream
+# The included file 'gh-project.mk' should define the following:
+# GH_SOURCE_DIR = top-level directory of all the ReST source files
+# GH_SOURCE_BRANCH = repository branch that contains the source
+# GH_PUBLISH_BRANCH = repository branch that contains the rendered HTML
+# GH_UPSTREAM_REPO = repository that contains the rendered HTML
+include gh-project.mk
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = ./build
+BUILDDIR      = ./gh-build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(GH_SOURCE_DIR)
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(GH_SOURCE_DIR)
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
@@ -49,26 +47,23 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
-clean:
-	-rm -rf $(GH_BUILT_DIRS) $(GH_BUILT_FILES)
+gh-clean gh-revert clean:
+	-rm -rf $(BUILDDIR)
 
 gh-preview html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
 
-gh-revert:
-	-rm -rf $(BUILDDIR)
-
-gh-pages:
-	git checkout $(GH_BUILD_BRANCH)
-	git checkout $(GH_SOURCE_BRANCH) -- $(GH_SOURCE_DIRS)
+gh-publish:
+	git checkout $(GH_PUBLISH_BRANCH)
+	git checkout $(GH_SOURCE_BRANCH) -- $(GH_SOURCE_DIR)
 	git reset HEAD 
 	make html
 	rsync -a $(BUILDDIR)/* .
-	rm -rf $(GH_SOURCE_DIRS) build
+	rm -rf $(GH_SOURCE_DIR) $(BUILDDIR)
 	git add -A 
-	git commit -m "Generated $(GH_BUILD_BRANCH) for `git log $(GH_SOURCE_BRANCH) -1 --pretty=short --abbrev-commit`" && git push $(GH_CYCLUS_REMOTE) $(GH_BUILD_BRANCH)
+	git commit -m "Generated $(GH_PUBLISH_BRANCH) for `git log $(GH_SOURCE_BRANCH) -1 --pretty=short --abbrev-commit`" && git push $(GH_UPSTREAM_REPO) $(GH_PUBLISH_BRANCH)
 	git checkout $(GH_SOURCE_BRANCH)
 
 htmlclean cleanhtml: clean html

README.rst

@@ -50,7 +50,7 @@ Best practice workflow for contributing to site changes
 
    ``make gh-preview``
 
-   This will build a version of the site in the `build` directory of
+   This will build a version of the site in the `gh-build` directory of
    your branch, `add_some_info`.  You can load it directly in a local
    browser.
 
@@ -83,17 +83,14 @@ Best practice for managing a pull request
 
 3. Test the changes by using the `gh-preview` target
 
-   ``make gh-preview``
-
-   This will build a version of the site in the `build` directory in
+   This will build a version of the site in the `gh-build` directory in
    your branch, `pull_request_branch`.  You can load it directly in a
    local browser.
 
-5. If satisfied, merge the `pull_request_branch` into the `source`
+4. If satisfied, merge the `pull_request_branch` into the `source`
    branch.  Be sure to synchronize with the remote repo first.
 
    ::
-
      git checkout source
      git fetch upstream
      git rebase upstream/source

gh-project.mk

@@ -0,0 +1,18 @@
+# Example for a Github hosted domain account: account.github.io
+#
+# GH_SOURCE_DIR = top-level directory of all the ReST source files
+GH_SOURCE_DIR = source
+# GH_SOURCE_BRANCH = repository branch that contains the source
+GH_SOURCE_BRANCH = source
+# GH_PUBLISH_BRANCH = repository branch that contains the rendered HTML
+GH_PUBLISH_BRANCH = master
+# GH_UPSTREAM_REPO = repository that contains the rendered HTML
+GH_UPSTREAM_REPO = upstream
+
+
+# Example for a gh-pages project
+#
+# GH_SOURCE_DIR = doc-src
+# GH_SOURCE_BRANCH = master
+# GH_PUBLISH_BRANCH = gh-pages
+# GH_UPSTREAM_REPO = upstream