gh-pages includes pdf

also fixed illegal image name in latex

closes gh-267

docs/Makefile

@@ -1,110 +1,110
 # 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
+gh-pages: html pdf
 	python gh-pages.py
 
-gh-pages-current: html
-	python gh-pages.py current
+gh-pages-current: html pdf
+	python gh-pages.py current "Current Development Version"

docs/gh-pages.py

@@ -1,143 +1,158
 #!/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_htmlindex(fname, tag):
-    rel = '<li> Release: <a href="{t}/index.html">{t}</a>'.format(t=tag)
+def render_htmlindex(fname, tag, desc=None):
+    if desc is None:
+        desc = tag
+        
+    rel = '<li>{d}: <a href="{t}/index.html">HTML</a> and <a href="{t}/ipython.pdf">PDF</a>'.format(t=tag,d=desc)
     rep = re.compile('<!-- RELEASE -->')
     out = []
     with file(fname) as f:
-        for line in 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 ''.join(out)
+    return '\n'.join(out)+'\n'
 
 
-def new_htmlindex(fname, tag):
-    new_page = render_htmlindex(fname, tag)
+def new_htmlindex(fname, tag, desc=None):
+    new_page = render_htmlindex(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:
         tag = sh2('git describe')
 
+    try:
+        desc = sys.argv[2]
+    except IndexError:
+        desc="Release (%s)"%tag
+    
     startdir = os.getcwd()
     if not os.path.exists(pages_dir):
         init_repo(pages_dir)
 
     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)
         sh('git checkout gh-pages')
         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_htmlindex('index.html', tag)
+        new_htmlindex('index.html', tag, desc)
         sh('git add index.html')
         sh('git commit -m"Created new doc release, named: %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/interactive/qtconsole.txt

@@ -1,219 +1,219
 .. _qtconsole:
 
 =========================
 IPython as a QtGUI widget
 =========================
 
 We now have a version of IPython, using the new two-process :ref:`ZeroMQ Kernel <ipythonzmq>`,
 running in a PyQt_ GUI.
 
 Overview
 ========
 
 The Qt frontend has hand-coded emacs-style bindings for text navigation. This is not yet
 configurable.
 
 .. seealso:: 
 
     `The original IPython-Qt project description. <ipython_qt>`_
     
 ``%loadpy``
 ===========
 
 The ``%loadpy`` magic has been added, just for the GUI frontend. It takes any python
 script (must end in '.py'), and pastes its contents as your next input, so you can edit it
 before executing. The script may be on your machine, but you can also specify a url, and
 it will download the script from the web. This is particularly useful for playing with
 examples from documentation, such as matplotlib.
 
 .. sourcecode:: ipython
 
     In [6]: %loadpy 
     http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py
 
     In [7]: from mpl_toolkits.mplot3d import axes3d
        ...: import matplotlib.pyplot as plt
        ...: 
        ...: fig = plt.figure()
        ...: ax = fig.add_subplot(111, projection='3d')
        ...: X, Y, Z = axes3d.get_test_data(0.05)
        ...: cset = ax.contour(X, Y, Z)
        ...: ax.clabel(cset, fontsize=9, inline=1)
        ...: 
        ...: plt.show()
 
 Pylab
 =====
 
 One of the most exciting features of the new console is embedded matplotlib figures. You
 can use any standard matplotlib GUI backend (Except native MacOSX) to draw the figures,
 and since there is now a two-process model, there is no longer a conflict between user
 input and the drawing eventloop.
 
 .. image:: figs/besselj.png
     :width: 519px
 
 .. pastefig:
 
 :func:`pastefig`
 ****************
 
 An additional function, :func:`pastefig`, will be added to the global namespace if you
 specify the ``--pylab`` argument. This takes the active figures in matplotlib, and embeds
 them in your document. This is especially useful for saving_ your work.
 
 .. _inline:
 
 ``--pylab inline``
 ******************
 
 If you want to have all of your figures embedded in your session, instead of calling
 :func:`pastefig`, you can specify ``--pylab inline``, and each time you make a plot, it
 will show up in your document, as if you had called :func:`pastefig`.
 
 
 .. _saving:
 
 Saving and Printing
 ===================
 
 IPythonQt has the ability to save your current session, as either HTML or XHTML. If you
 have been using `pastefig <pastefig>`_ or inline_ pylab, your figures will be PNG
 in HTML, or inlined as SVG in XHTML. PNG images have the option to be either in an
 external folder, as in many browsers' "Webpage, Complete" option, or inlined as well, for
 a larger, but more portable file.
 
 The widget also exposes the ability to print directly, via the default print shortcut or
 context menu.
 
 
 .. Note:: 
 
     Saving is only available to richtext Qt widgets, so make sure you start ipqt with the
     ``--rich`` flag, or with ``--pylab``, which always uses a richtext widget.
 
 
 See these examples of :download:`png/html<figs/jn.html>` and :download:`svg/xhtml
 <figs/jn.xhtml>` output. Note that syntax highlighting does not survive export. This is a known
 issue, and is being investigated.
 
 Colors and Highlighting
 =======================
 
 Terminal IPython has always had some coloring, but never syntax highlighting. There are a
 few simple color choices, specified by the ``--colors`` flag or ``%colors`` magic:
 
 * LightBG for light backgrounds
 * Linux for dark backgrounds
 * NoColor for a simple colorless terminal
 
 The Qt widget has full support for the ``--colors`` flag, but adds new, more intuitive
 aliases for the colors (the old names still work): dark=Linux, light=LightBG, bw=NoColor.
 
 The Qt widget, however, has full syntax highlighting as you type, handled by the
 `pygments`_ library. The ``--style`` argument exposes access to any style by name that can
 be found by pygments, and there are several already installed. The ``--colors`` argument,
 if unspecified, will be guessed based on the chosen style. Similarly, there are default
 styles associated with each ``--colors`` option.
 
 
 Screenshot of ``ipython-qtconsole --colors dark``, which uses the 'monokai' theme by
 default:
 
-.. image:: figs/colors.dark.png
+.. image:: figs/colors_dark.png
     :width: 627px
     
 .. Note::
 
     Calling ``ipython-qtconsole -h`` will show all the style names that pygments can find
     on your system.
 
 You can also pass the filename of a custom CSS stylesheet, if you want to do your own
 coloring, via the ``--stylesheet`` argument.  The default LightBG stylesheet:
 
 .. sourcecode:: css
 
     QPlainTextEdit, QTextEdit { background-color: white;
             color: black ;
             selection-background-color: #ccc}
     .error { color: red; }
     .in-prompt { color: navy; }
     .in-prompt-number { font-weight: bold; }
     .out-prompt { color: darkred; }
     .out-prompt-number { font-weight: bold; }
 
 Process Management
 ==================
 
 With the two-process ZMQ model, the frontend does not block input during execution. This
 means that actions can be taken by the frontend while the Kernel is executing, or even
 after it crashes. The most basic such command is via 'Ctrl-.', which restarts the kernel.
 This can be done in the middle of a blocking execution. The frontend can also know, via a
 heartbeat mechanism, that the kernel has died. This means that the frontend can safely
 restart the kernel.
 
 Multiple Consoles
 *****************
 
 Since the Kernel listens on the network, multiple frontends can connect to it.  These
 do not have to all be qt frontends - any IPython frontend can connect and run code.
 When you start ipython-qtconsole, there will be an output line, like::
 
     To connect another client to this kernel, use:
     -e --xreq 62109 --sub 62110 --rep 62111 --hb 62112
 
 Other frontends can connect to your kernel, and share in the execution. This is great for
 collaboration. The `-e` flag is for 'external'. Starting other consoles with that flag
 will not try to start their own, but rather connect to yours. Ultimately, you will not
 have to specify each port individually, but for now this copy-paste method is best.
 
 By default (for security reasons), the kernel only listens on localhost, so you can only
 connect multiple frontends to the kernel from your local machine. You can specify to
 listen on an external interface by specifying the ``--ip`` argument::
 
     $> ipython-qtconsole --ip 192.168.1.123
 
 If you specify the ip as 0.0.0.0, that refers to all interfaces, so any computer that can
 see yours can connect to the kernel.
 
 .. warning::
 
     Since the ZMQ code currently has no security, listening on an external-facing IP
     is dangerous.  You are giving any computer that can see you on the network the ability
     to issue arbitrary shell commands as you on your machine. Be very careful with this.
 
 
 Stopping Kernels and Consoles
 *****************************
 
 Since there can be many consoles per kernel, the shutdown mechanism and dialog are
 probably more complicated than you are used to. Since you don't always want to shutdown a
 kernel when you close a window, you are given the option to just close the console window
 or also close the Kernel and *all other windows*. Note that this only refers to all other
 *local* windows, as remote Consoles are not allowed to shutdown the kernel, and shutdowns
 do not close Remote consoles (to allow for saving, etc.).
 
 Rules:
 
     * Restarting the kernel automatically clears all *local* Consoles, and prompts remote
       Consoles about the reset.
     * Shutdown closes all *local* Consoles, and notifies remotes that
       the Kernel has been shutdown.
     * Remote Consoles may not restart or shutdown the kernel.
 
 
 Regressions
 ===========
 
 There are some features, where the qt console lags behind the Terminal frontend. We hope
 to have these fixed by 0.11 release.
 
     * Configuration: The Qt frontend and ZMQ kernel are not yet hooked up to the IPython
       configuration system
     * History Persistence: Currently the history of a GUI session does
       not persist between sessions.
     * !cmd input: Due to our use of pexpect, we cannot pass input to subprocesses launched
       using the '!' escape. (this will not be fixed).
 
 .. [PyQt] PyQt4 http://www.riverbankcomputing.co.uk/software/pyqt/download
 .. [pygments] Pygments http://pygments.org/