Merge branch 'docs-build'

docs/gh-pages.py

@@ -110,7 +110,10 b" if __name__ == '__main__':"
     try:
         tag = sys.argv[1]
     except IndexError:
+        try:
         tag = sh2('git describe')
+        except CalledProcessError:
+            tag = "dev"   # Fallback
     
     try:
         desc = sys.argv[2]

docs/source/development/doc_guide.txt

@@ -134,6 +134,28 b' docutils (the machinery to process reStructuredText):'
    epydoc conventions.  We will update them as we go, but all new code should
    be documented using the NumPy standard.
 
+Building and uploading
+======================
+The built docs are stored in a separate repository. Through some github magic,
+they're automatically exposed as a website. It works like this:
+
+* You will need to have sphinx and latex installed. In Ubuntu, install
+  ``texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended``.
+  Install the latest version of sphinx from PyPI (``pip install sphinx``).
+* Ensure that the development version of IPython is the first in your system
+  path. You can either use a virtualenv, or modify your PYTHONPATH.
+* Switch into the docs directory, and run ``make gh-pages``. This will build
+  your updated docs as html and pdf, then automatically check out the latest
+  version of the docs repository, copy the built docs into it, and commit your
+  changes.
+* Open the built docs in a web browser, and check that they're as expected.
+* (If rebuilding the docs for the development version, it may have duplicated
+  the link to the development version in the homepage. Remove this from
+  index.rst, then run ``python build_index.py`` to update index.html. Commit the
+  change.)
+* Upload the docs with ``git push``. This only works if you have write access to
+  the docs repository.
+
 .. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
 .. [Sphinx] Sphinx. http://sphinx.pocoo.org/
 .. [MatplotlibDocGuide] http://matplotlib.sourceforge.net/devel/documenting_mpl.html