gh-pages.py no longer updates index.rst

docs/Makefile

@@ -1,111 +1,107 b''
 # Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 SRCDIR        = source
 
 # 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      to make standalone HTML files"
 	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 	@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:
 	-rm -rf build/* dist/* $(SRCDIR)/api/generated
 
 pdf: latex
 	cd build/latex && make all-pdf
 
 all: html pdf
 
 dist: all
 	mkdir -p dist
 	rm -rf dist/*
 	ln build/latex/ipython.pdf dist/
 	cp -al build/html dist/
 	@echo "Build finished.  Final docs are in dist/"
 
 html: api
 	mkdir -p build/html build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
 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."
 
 latex: api
 	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.txt."
 
 gitwash-update:
 	python ../tools/gitwash_dumper.py source/development ipython
 	cd source/development/gitwash && rename 's/.rst/.txt/' *.rst
 
 nightly: dist
 	rsync -avH --delete dist/ ipython:www/doc/nightly
 
 gh-pages: html pdf
 	python gh-pages.py
-
-gh-pages-current: html pdf
-	ipver="$(ipython -v 2>&1)"
-	python gh-pages.py dev "Current Development Version ($ipver)"

docs/gh-pages.py

@@ -1,168 +1,132 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.getcwd()
     cd(path)
     sh('git checkout gh-pages')
     cd(here)
 
-
-def render_rstindex(fname, tag, desc=None):
-    if desc is None:
-        desc = tag
-        
-    rel = '* {d}: `HTML <{t}/index.html>`_ and `PDF <{t}/ipython.pdf>`_.'.format(t=tag,d=desc)
-    rep = re.compile(r'\.\. release')
-    out = []
-    with file(fname) as f:
-        contents = f.read()
-    lines = contents.splitlines()
-    if rel in contents:
-        out = lines
-    else:
-        for line in lines:
-            out.append(line)
-            if rep.search(line):
-                out.append(rep.sub(rel, line))
-    return '\n'.join(out)+'\n'
-
-
-def new_rstindex(fname, tag, desc=None):
-    new_page = render_rstindex(fname, tag, desc)
-    os.rename(fname, fname+'~')
-    with file(fname, 'w') as f:
-        f.write(new_page)
-
-
 #-----------------------------------------------------------------------------
 # 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')
         except CalledProcessError:
             tag = "dev"   # Fallback
     
-    try:
-        desc = sys.argv[2]
-    except IndexError:
-        desc="Release (%s)"%tag
-    
     startdir = os.getcwd()
     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')
 
     # 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)
     shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf'))
 
     try:
         cd(pages_dir)
         status = sh2('git status | head -1')
         branch = re.match('\# On branch (.*)$', status).group(1)
         if branch != 'gh-pages':
             e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir,
                                                                  branch)
             raise RuntimeError(e)
 
         sh('git add %s' % tag)
-        new_rstindex('index.rst', tag, desc)
-        sh('python build_index.py')
-        sh('git add index.rst index.html')
-        sh('git commit -m"Created new doc release, named: %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'"

docs/source/development/doc_guide.txt

@@ -1,165 +1,167 b''
 .. _documenting-ipython:
 
 =====================
  Documenting IPython
 =====================
 
 When contributing code to IPython, you should strive for clarity and
 consistency, without falling prey to a style straitjacket.  Basically,
 'document everything, try to be consistent, do what makes sense.'
 
 By and large we follow existing Python practices in major projects like Python
 itself or NumPy, this document provides some additional detail for IPython.
 
 
 Standalone documentation
 ========================
 
 All standalone documentation should be written in plain text (``.txt``) files
 using reStructuredText [reStructuredText]_ for markup and formatting. All such
 documentation should be placed in the directory :file:`docs/source` of the
 IPython source tree. Or, when appropriate, a suitably named subdirectory
 should be used. The documentation in this location will serve as the main
 source for IPython documentation.
 
 The actual HTML and PDF docs are built using the Sphinx [Sphinx]_
 documentation generation tool. Once you have Sphinx installed, you can build
 the html docs yourself by doing:
 
 .. code-block:: bash
 
     $ cd ipython-mybranch/docs
     $ make html
 
 Our usage of Sphinx follows that of matplotlib [Matplotlib]_ closely. We are
 using a number of Sphinx tools and extensions written by the matplotlib team
 and will mostly follow their conventions, which are nicely spelled out in
 their documentation guide [MatplotlibDocGuide]_. What follows is thus a
 abridged version of the matplotlib documentation guide, taken with permission
 from the matplotlib team.
 
 If you are reading this in a web browser, you can click on the "Show Source"
 link to see the original reStricturedText for the following examples.
 
 A bit of Python code::
 
     for i in range(10):
         print i,
     print "A big number:",2**34
 
 An interactive Python session::
 
     >>> from IPython.utils.path import get_ipython_dir
     >>> get_ipython_dir()
     '/home/fperez/.ipython'
 
 An IPython session:
 
 .. code-block:: ipython
 
   In [7]: import IPython
 
   In [8]: print "This IPython is version:",IPython.__version__
   This IPython is version: 0.9.1
 
   In [9]: 2+4
   Out[9]: 6
 
 
 A bit of shell code:
 
 .. code-block:: bash
 
     cd /tmp
     echo "My home directory is: $HOME"
     ls
 
 Docstring format
 ================
 
 Good docstrings are very important.  Unfortunately, Python itself only provides
 a rather loose standard for docstrings [PEP257]_, and there is no universally
 accepted convention for all the different parts of a complete docstring.
 However, the NumPy project has established a very reasonable standard, and has
 developed some tools to support the smooth inclusion of such docstrings in
 Sphinx-generated manuals.  Rather than inventing yet another pseudo-standard,
 IPython will be henceforth documented using the NumPy conventions; we carry
 copies of some of the NumPy support tools to remain self-contained, but share
 back upstream with NumPy any improvements or fixes we may make to the tools.
 
 The NumPy documentation guidelines [NumPyDocGuide]_ contain detailed
 information on this standard, and for a quick overview, the NumPy example
 docstring [NumPyExampleDocstring]_ is a useful read.
 
 
 For user-facing APIs, we try to be fairly strict about following the above
 standards (even though they mean more verbose and detailed docstrings).
 Wherever you can reasonably expect people to do introspection with::
 
   In [1]: some_function?
 
 the docstring should follow the NumPy style and be fairly detailed.
 
 For purely internal methods that are only likely to be read by others extending
 IPython itself we are a bit more relaxed, especially for small/short methods
 and functions whose intent is reasonably obvious.  We still expect docstrings
 to be written, but they can be simpler.  For very short functions with a
 single-line docstring you can use something like::
 
     def add(a, b):
        """The sum of two numbers.
        """
        code
 
 and for longer multiline strings::
 
     def add(a, b):
        """The sum of two numbers.
 
        Here is the rest of the docs.
        """
        code
 
 
 Here are two additional PEPs of interest regarding documentation of code.
 While both of these were rejected, the ideas therein form much of the basis of
 docutils (the machinery to process reStructuredText):
 
 * `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
 * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
 
 .. note::
 
    In the past IPython used epydoc so currently many docstrings still use
    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
+* (When building the docs for a new tagged release, you will have to add its link to
+  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.
+* If you are building a version that is not the current dev branch, nor a tagged release,
+  then you must run gh-pages.py directly with ``python gh-pages.py <version>``, and *not*
+  with ``make gh-pages``.
 
 .. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
 .. [Sphinx] Sphinx. http://sphinx.pocoo.org/
 .. [MatplotlibDocGuide] http://matplotlib.sourceforge.net/devel/documenting_mpl.html
 .. [PEP257] PEP 257.  http://www.python.org/peps/pep-0257.html
 .. [NumPyDocGuide] NumPy documentation guide.  http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
 .. [NumPyExampleDocstring] NumPy example docstring. http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt