From 1df654b8a9bdb0ef35100d33487d3b650ddc23ab Mon Sep 17 00:00:00 2001 From: "Paul P.H. Wilson" Date: Tue, 6 Aug 2013 12:01:53 -0500 Subject: [PATCH] Generalize the Makefile and improve instructions --- Makefile | 37 ++++++++++++++++--------------------- README.rst | 9 +++------ gh-project.mk | 18 ++++++++++++++++++ 3 files changed, 37 insertions(+), 27 deletions(-) create mode 100644 gh-project.mk diff --git a/Makefile b/Makefile index 9c2cf6b56..e4fc06de1 100644 --- a/Makefile +++ b/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 diff --git a/README.rst b/README.rst index 19cef81a0..da58a1fcb 100644 --- a/README.rst +++ b/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 diff --git a/gh-project.mk b/gh-project.mk new file mode 100644 index 000000000..508e2fab9 --- /dev/null +++ b/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