build docs with Python 3

docs/Makefile

@@ -147,6 +147,8 @@ gh-pages: clean html
 	# if VERSION is unspecified, it will be dev
 	# For releases, VERSION should be just the major version,
 	# e.g. VERSION=2 make gh-pages
+	# use ARCHIVE=1 VERSION=3 gh-pages to build the
+	# docs with a warning that this is not stable docs anymore.
 	python gh-pages.py $(VERSION)
 
 texinfo:

docs/gh-pages.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+from __future__ import print_function
 """Script to commit the doc build outputs into the github-pages repo.
 
 Use:
@@ -14,7 +15,6 @@
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from __future__ import print_function
 
 import os
 import shutil
@@ -33,6 +33,12 @@
 pdf_dir = 'build/latex'
 pages_repo = 'git@github.com:ipython/ipython-doc.git'
 
+
+if sys.version_info[0] <= 3: 
+    getcwd = os.getcwd
+else:
+    getcwd = os.getcwdu
+
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
@@ -70,7 +76,7 @@ def sh3(cmd):
 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()
+    here = getcwd()
     cd(path)
     sh('git checkout gh-pages')
     cd(here)
@@ -85,7 +91,7 @@ def init_repo(path):
     except IndexError:
         tag = "dev"
 
-    startdir = os.getcwdu()
+    startdir = getcwd()
     if not os.path.exists(pages_dir):
         # init the repo
         init_repo(pages_dir)
@@ -116,7 +122,7 @@ def init_repo(path):
     try:
         cd(pages_dir)
         branch = sh2('git rev-parse --abbrev-ref HEAD').strip()
-        if branch != 'gh-pages':
+        if branch != b'gh-pages':
             e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir,
                                                                  branch)
             raise RuntimeError(e)

docs/requirements.txt

@@ -0,0 +1,8 @@
+numpydoc
+sphinx
+pygments
+oct2py
+cython
+nose
+pymongo
+fabric

docs/source/conf.py

@@ -78,6 +78,15 @@
 
     """
 
+elif os.environ.get('ARCHIVE', None):
+    rst_prolog = """
+    .. warning::
+
+        This documentation is for an old version of IPython.
+        You can find docs for newer versions `here <http://ipython.readthedocs.org/en/stable/>`_.
+
+    """
+
 # The master toctree document.
 master_doc = 'index'