require specifying the version for gh-pages

From now on, we are only maintaining one build of the IPython docs per major release, e.g. latest 1.x docs served at ipython-doc/1/. This makes gh-pages no longer guess based on git tag. To build the 1.x docs:

    VERSION=1 make gh-pages

docs/Makefile

@@ -1,151 +1,154 b''
 # Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 SRCDIR        = source
 BUILDDIR      = build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
 
 default: html
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html        standalone HTML files"
 	@echo "  html_noapi  same as above, without the time consuming API docs"
 	@echo "  pickle      pickle files (usable by e.g. sphinx-web)"
 	@echo "  htmlhelp    HTML files and a HTML help project"
 	@echo "  latex       LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  texinfo     Texinfo files"
 	@echo "  info        Texinfo files and run them through makeinfo"
 	@echo "  changes     an overview over all changed/added/deprecated items"
 	@echo "  linkcheck   check all external links for integrity (takes a long time)"
 	@echo
 	@echo "Compound utility targets:"
 	@echo "pdf          latex and then runs the PDF generation"
 	@echo "all          html and pdf"
 	@echo "dist         all, and then puts the results in dist/"
 	@echo "gitwash-update update git workflow from source repo"
 
 clean_api:
 	-rm -rf $(SRCDIR)/api/generated
 
 clean: clean_api
 	-rm -rf build/* dist/*
 	-rm -rf $(SRCDIR)/config/options/generated
 
 pdf: latex
 	cd build/latex && make all-pdf
 
 all: html pdf
 
 # For final distribution, only build HTML (our pdf is now so large as to be
 # unusable, takes forever to build and just bloats the downloads).  We leave
 # them hardlinked at the top-level so users find them easily, though the
 # original build/html dir is left in-place (useful to reload builds while
 # testing).
 dist: html
 	rm -rf html
 	cp -al build/html .
 	@echo "Build finished.  Final docs are in html/"
 
 html: api autoconfig
 html_noapi: clean_api autoconfig
 
 html html_noapi:
 	mkdir -p build/html build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
 autoconfig: source/config/options/generated
 
 source/config/options/generated:
 	python autogen_config.py
 	@echo "Created docs for config options"
 
 api: source/api/generated/gen.txt
 
 source/api/generated/gen.txt:
 	python autogen_api.py
 	@echo "Build API docs finished."
 
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files or run"
 	@echo "  sphinx-web build/pickle"
 	@echo "to start the sphinx-web server."
 
 web: pickle
 
 htmlhelp:
 	mkdir -p build/htmlhelp build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in build/htmlhelp."
 
 qthelp:
 	mkdir -p build/qthelp
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
 
 latex: api autoconfig
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
 	mkdir -p build/changes build/doctrees
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
 	@echo
 	@echo "The overview file is in build/changes."
 
 linkcheck:
 	mkdir -p build/linkcheck build/doctrees
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.rst."
 
 gitwash-update:
 	python ../tools/gitwash_dumper.py source/development ipython
 
 nightly: dist
 	rsync -avH --delete dist/ ipython:www/doc/nightly
 
 gh-pages: clean html
-	python gh-pages.py
+	# if VERSION is unspecified, it will be dev
+	# For releases, VERSION should be just the major version,
+	# e.g. VERSION=2 make gh-pages
+	python gh-pages.py $(VERSION)
 
 texinfo:
 	mkdir -p $(BUILDDIR)/texinfo
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
 info:
 	mkdir -p $(BUILDDIR)/texinfo
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

docs/gh-pages.py

@@ -1,138 +1,134 b''
 #!/usr/bin/env python
 """Script to commit the doc build outputs into the github-pages repo.
 
 Use:
 
   gh-pages.py [tag]
 
 If no tag is given, the current output of 'git describe' is used.  If given,
 that is how the resulting directory will be named.
 
 In practice, you should use either actual clean tags from a current build or
 something like 'current' as a stable URL for the most current version of the """
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 import os
 import re
 import shutil
 import sys
 from os import chdir as cd
 from os.path import join as pjoin
 
 from subprocess import Popen, PIPE, CalledProcessError, check_call
 
 #-----------------------------------------------------------------------------
 # Globals
 #-----------------------------------------------------------------------------
 
 pages_dir = 'gh-pages'
 html_dir = 'build/html'
 pdf_dir = 'build/latex'
 pages_repo = '[e-mail]:ipython/ipython-doc.git'
 
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
 def sh(cmd):
     """Execute command in a subshell, return status code."""
     return check_call(cmd, shell=True)
 
 
 def sh2(cmd):
     """Execute command in a subshell, return stdout.
 
     Stderr is unbuffered from the subshell.x"""
     p = Popen(cmd, stdout=PIPE, shell=True)
     out = p.communicate()[0]
     retcode = p.returncode
     if retcode:
         raise CalledProcessError(retcode, cmd)
     else:
         return out.rstrip()
 
 
 def sh3(cmd):
     """Execute command in a subshell, return stdout, stderr
 
     If anything appears in stderr, print it out to sys.stderr"""
     p = Popen(cmd, stdout=PIPE, stderr=PIPE, shell=True)
     out, err = p.communicate()
     retcode = p.returncode
     if retcode:
         raise CalledProcessError(retcode, cmd)
     else:
         return out.rstrip(), err.rstrip()
 
 
 def init_repo(path):
     """clone the gh-pages repo if we haven't already."""
     sh("git clone %s %s"%(pages_repo, path))
     here = os.getcwdu()
     cd(path)
     sh('git checkout gh-pages')
     cd(here)
 
 #-----------------------------------------------------------------------------
 # Script starts
 #-----------------------------------------------------------------------------
 if __name__ == '__main__':
     # The tag can be given as a positional argument
     try:
         tag = sys.argv[1]
     except IndexError:
-        try:
-            tag = sh2('git describe --exact-match')
-        except CalledProcessError:
-            tag = "dev"   # Fallback
+        tag = "dev"
     
     startdir = os.getcwdu()
     if not os.path.exists(pages_dir):
         # init the repo
         init_repo(pages_dir)
     else:
         # ensure up-to-date before operating
         cd(pages_dir)
         sh('git checkout gh-pages')
         sh('git pull')
         cd(startdir)
 
     dest = pjoin(pages_dir, tag)
 
     # don't `make html` here, because gh-pages already depends on html in Makefile
     # sh('make html')
     if tag != 'dev':
         # only build pdf for non-dev targets
         #sh2('make pdf')
         pass
 
     # This is pretty unforgiving: we unconditionally nuke the destination
     # directory, and then copy the html tree in there
     shutil.rmtree(dest, ignore_errors=True)
     shutil.copytree(html_dir, dest)
     if tag != 'dev':
         #shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf'))
         pass
 
     try:
         cd(pages_dir)
-        status = sh2('git status | head -1')
-        branch = re.match('\# On branch (.*)$', status).group(1)
+        branch = sh2('git rev-parse --abbrev-ref HEAD').strip()
         if branch != 'gh-pages':
             e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir,
                                                                  branch)
             raise RuntimeError(e)
 
         sh('git add -A %s' % tag)
         sh('git commit -m"Updated doc release: %s"' % tag)
         print
         print 'Most recent 3 commits:'
         sys.stdout.flush()
         sh('git --no-pager log --oneline HEAD~3..')
     finally:
         cd(startdir)
 
     print
     print 'Now verify the build in: %r' % dest
     print "If everything looks good, 'git push'"