Update docs for automatic API building.

docs/autogen_api.py

@@ -0,0 +1,33 b''
+#!/usr/bin/env python
+"""Script to auto-generate our API docs.
+"""
+# stdlib imports
+import os
+import sys
+
+# local imports
+sys.path.append(os.path.abspath('sphinxext'))
+from apigen import ApiDocWriter
+
+#*****************************************************************************
+if __name__ == '__main__':
+    pjoin = os.path.join
+    package = 'IPython'
+    outdir = pjoin('source','api','generated')
+    docwriter = ApiDocWriter(package,rst_extension='.txt')
+    docwriter.package_skip_patterns += [r'\.fixes$',
+                                        r'\.externals$',
+                                        r'\.Extensions',
+                                        r'\.kernel.config',
+                                        r'\.attic',
+                                        ]
+    docwriter.module_skip_patterns += [ r'\.FakeModule',
+                                        r'\.cocoa',
+                                        r'\.ipdoctest',
+                                        r'\.Gnuplot',
+                                        ]
+    docwriter.write_api_docs(outdir)
+    docwriter.write_index(outdir, 'gen',
+                          relative_to = pjoin('source','api')
+                          )
+    print '%d files written' % len(docwriter.written_modules)

docs/source/api/index.txt

@@ -0,0 +1,12 b''
+.. _api-index:
+
+###################
+  The IPython API
+###################
+
+.. htmlonly::
+
+   :Release: |version|
+   :Date: |today|
+
+.. include:: generated/gen.txt

docs/source/parallel/visionhpc.txt

@@ -0,0 +1,246 b''
+==================================
+ IPython/Vision Beam Pattern Demo
+==================================
+
+
+Installing and testing IPython at OSC systems
+=============================================
+
+All components were installed from source and I have my environment set up to
+include ~/usr/local in my various necessary paths ($PATH, $PYTHONPATH, etc).
+Other than a slow filesystem for unpacking tarballs, the install went without a
+hitch.  For each needed component, I just downloaded the source tarball,
+unpacked it via::
+
+  tar xzf (or xjf if it's bz2) filename.tar.{gz,bz2}
+
+and then installed them (including IPython itself) with::
+
+  cd dirname/  # path to unpacked tarball
+  python setup.py install --prefix=~/usr/local/
+
+The components I installed are listed below.  For each one I give the main
+project link as well as a direct one to the file I actually dowloaded and used.
+
+- nose, used for testing:
+http://somethingaboutorange.com/mrl/projects/nose/
+http://somethingaboutorange.com/mrl/projects/nose/nose-0.10.3.tar.gz
+
+- Zope interface, used to declare interfaces in twisted and ipython.  Note:
+you must get this from the page linked below and not fro the defaul
+one(http://www.zope.org/Products/ZopeInterface) because the latter has an
+older version, it hasn't been updated in a long time.  This pypi link has
+the current release (3.4.1 as of this writing):
+http://pypi.python.org/pypi/zope.interface
+http://pypi.python.org/packages/source/z/zope.interface/zope.interface-3.4.1.tar.gz
+
+- pyopenssl, security layer used by foolscap.  Note: version 0.7 *must* be
+used: 
+http://sourceforge.net/projects/pyopenssl/
+http://downloads.sourceforge.net/pyopenssl/pyOpenSSL-0.6.tar.gz?modtime=1212595285&big_mirror=0
+
+
+- Twisted, used for all networking:
+http://twistedmatrix.com/trac/wiki/Downloads
+http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2
+
+- Foolscap, used for managing connections securely:
+http://foolscap.lothar.com/trac
+http://foolscap.lothar.com/releases/foolscap-0.3.1.tar.gz
+
+
+- IPython itself:
+http://ipython.scipy.org/
+http://ipython.scipy.org/dist/ipython-0.9.1.tar.gz
+
+
+I then ran the ipython test suite via::
+
+  iptest -vv
+
+and it passed with only::
+
+    ======================================================================
+    ERROR: testGetResult_2
+    ----------------------------------------------------------------------
+    DirtyReactorAggregateError: Reactor was unclean.
+    Selectables:
+    <Negotiation #0 on 10105>
+
+    ----------------------------------------------------------------------
+    Ran 419 tests in 33.971s
+
+    FAILED (SKIP=4, errors=1)
+
+In three more runs of the test suite I was able to reproduce this error
+sometimes but not always; for now I think we can move on but we need to
+investigate further.  Especially if we start seeing problems in real use (the
+test suite stresses the networking layer in particular ways that aren't
+necessarily typical of normal use).
+
+Next, I started an 8-engine cluster via::
+
+    perez@opt-login01[~]> ipcluster -n 8
+    Starting controller: Controller PID: 30845
+    ^X      Starting engines:    Engines PIDs:   [30846, 30847, 30848, 30849,
+    30850, 30851, 30852, 30853]
+    Log files: /home/perez/.ipython/log/ipcluster-30845-*
+
+    Your cluster is up and running.
+
+    [... etc]
+
+and in a separate ipython session checked that the cluster is running and I can
+access all the engines::
+
+    In [1]: from IPython.kernel import client
+
+    In [2]: mec = client.MultiEngineClient()
+
+    In [3]: mec.get_ids()
+    Out[3]: [0, 1, 2, 3, 4, 5, 6, 7]
+
+and run trivial code in them (after importing the ``random`` module in all
+engines)::
+
+    In [11]: mec.execute("x=random.randint(0,10)")
+    Out[11]:
+    <Results List>
+    [0] In [3]: x=random.randint(0,10)
+    [1] In [3]: x=random.randint(0,10)
+    [2] In [3]: x=random.randint(0,10)
+    [3] In [3]: x=random.randint(0,10)
+    [4] In [3]: x=random.randint(0,10)
+    [5] In [3]: x=random.randint(0,10)
+    [6] In [3]: x=random.randint(0,10)
+    [7] In [3]: x=random.randint(0,10)
+
+    In [12]: mec.pull('x')
+    Out[12]: [10, 0, 8, 10, 2, 9, 10, 7]
+
+
+We'll continue conducting more complex tests later, including instaling Vision
+locally and running the beam demo.
+
+
+Michel's original instructions
+==============================
+
+I got a Vision network that reproduces the beam pattern demo working:
+
+.. image:: vision_beam_pattern.png
+   :width: 400
+   :target: vision_beam_pattern.png
+   :align: center
+
+
+I created a package called beamPattern that provides the function run() in its
+__init__.py file.
+
+A subpackage beamPattern/VisionInterface provides Vision nodes for:
+
+- computing Elevation and Azimuth from a 3D vector
+
+- Reading .mat files
+
+- taking the results gathered from the engines and creating the output that a
+  single engine would have had produced
+
+The Mec node connect to a controller. In my network it was local but an furl
+can be specified to connect to a remote controller.
+
+The PRun Func node is from the IPython library of nodes. the import statement
+is used to get the run function from the beamPattern package and bu puting
+"run" in the function entry of this node we push this function to the engines.
+In addition to the node will create input ports for all arguments of the
+function being pushed (i.e. the run function)
+
+The second input port on PRun Fun take an integer specifying the rank of the
+argument we want to scatter. All other arguments will be pushed to the engines.
+
+The ElevAzim node has a 3D vector widget and computes the El And Az values
+which are passed into the PRun Fun node through the ports created
+automatically. The Mat node allows to select the .mat file, reads it and passed
+the data to the locdata port created automatically on PRun Func
+
+The calculation is executed in parallel, and the results are gathered and
+output.  Instead of having a list of 3 vectors we nd up with a list of n*3
+vectors where n is the number of engines. unpackDectorResults will turn it into
+a list of 3. We then plot x, y, and 10*log10(z)
+
+
+Installation
+------------
+
+- inflate beamPattern into the site-packages directory for the MGL tools.
+
+- place the appended IPythonNodes.py and StandardNodes.py into the Vision
+  package of the MGL tools.
+
+- place the appended items.py in the NetworkEditor package of the MGL tools
+
+- run vision for the network beamPat5_net.py::
+
+    vision beamPat5_net.py
+
+Once the network is running, you can:
+
+- double click on the MEC node and either use an emptty string for the furl to
+  connect to a local engine or cut and paste the furl to the engine you want to
+  use
+
+- click on the yellow lighting bold to run the network.
+
+- Try modifying the MAT file or change the Vector used top compute elevation
+  and Azimut.
+  
+
+Fernando's notes
+================
+
+- I had to install IPython and all its dependencies for the python used by the
+  MGL tools.
+
+- Then I had to install scipy 0.6.0 for it, since the nodes needed Scipy.  To
+  do this I sourced the mglenv.sh script and then ran::
+
+    python setup.py install --prefix=~/usr/opt/mgl
+
+
+Using PBS
+=========
+
+The following PBS script can be used to start the engines::
+
+    #PBS -N bgranger-ipython
+    #PBS -j oe
+    #PBS -l walltime=00:10:00
+    #PBS -l nodes=4:ppn=4
+
+    cd $PBS_O_WORKDIR
+    export PATH=$HOME/usr/local/bin
+    export PYTHONPATH=$HOME/usr/local/lib/python2.4/site-packages
+    /usr/local/bin/mpiexec -n 16 ipengine
+
+
+If this file is called ``ipython_pbs.sh``, then the in one login windows
+(i.e. on the head-node -- ``opt-login01.osc.edu``), run ``ipcontroller``. In
+another login window on the same node, run the above script::
+
+    qsub ipython_pbs.sh
+
+If you look at the first window, you will see some diagnostic output
+from ipcontroller. You can then get the furl from your own
+``~/.ipython/security`` directory and then connect to it remotely.
+
+You might need to set up an SSH tunnel, however; if this doesn't work as
+advertised::
+
+    ssh -L 10115:localhost:10105 bic
+
+
+Links to other resources
+========================
+
+- http://www.osc.edu/~unpingco/glenn_NewLynx2_Demo.avi
+

docs/sphinxext/docscrape.py

@@ -0,0 +1,497 b''
+"""Extract reference documentation from the NumPy source tree.
+
+"""
+
+import inspect
+import textwrap
+import re
+import pydoc
+from StringIO import StringIO
+from warnings import warn
+4
+class Reader(object):
+    """A line-based string reader.
+
+    """
+    def __init__(self, data):
+        """
+        Parameters
+        ----------
+        data : str
+           String with lines separated by '\n'.
+
+        """
+        if isinstance(data,list):
+            self._str = data
+        else:
+            self._str = data.split('\n') # store string as list of lines
+
+        self.reset()
+
+    def __getitem__(self, n):
+        return self._str[n]
+
+    def reset(self):
+        self._l = 0 # current line nr
+
+    def read(self):
+        if not self.eof():
+            out = self[self._l]
+            self._l += 1
+            return out
+        else:
+            return ''
+
+    def seek_next_non_empty_line(self):
+        for l in self[self._l:]:
+            if l.strip():
+                break
+            else:
+                self._l += 1
+
+    def eof(self):
+        return self._l >= len(self._str)
+
+    def read_to_condition(self, condition_func):
+        start = self._l
+        for line in self[start:]:
+            if condition_func(line):
+                return self[start:self._l]
+            self._l += 1
+            if self.eof():
+                return self[start:self._l+1]
+        return []
+
+    def read_to_next_empty_line(self):
+        self.seek_next_non_empty_line()
+        def is_empty(line):
+            return not line.strip()
+        return self.read_to_condition(is_empty)
+
+    def read_to_next_unindented_line(self):
+        def is_unindented(line):
+            return (line.strip() and (len(line.lstrip()) == len(line)))
+        return self.read_to_condition(is_unindented)
+
+    def peek(self,n=0):
+        if self._l + n < len(self._str):
+            return self[self._l + n]
+        else:
+            return ''
+
+    def is_empty(self):
+        return not ''.join(self._str).strip()
+
+
+class NumpyDocString(object):
+    def __init__(self,docstring):
+        docstring = textwrap.dedent(docstring).split('\n')
+
+        self._doc = Reader(docstring)
+        self._parsed_data = {
+            'Signature': '',
+            'Summary': [''],
+            'Extended Summary': [],
+            'Parameters': [],
+            'Returns': [],
+            'Raises': [],
+            'Warns': [],
+            'Other Parameters': [],
+            'Attributes': [],
+            'Methods': [],
+            'See Also': [],
+            'Notes': [],
+            'Warnings': [],
+            'References': '',
+            'Examples': '',
+            'index': {}
+            }
+
+        self._parse()
+
+    def __getitem__(self,key):
+        return self._parsed_data[key]
+
+    def __setitem__(self,key,val):
+        if not self._parsed_data.has_key(key):
+            warn("Unknown section %s" % key)
+        else:
+            self._parsed_data[key] = val
+
+    def _is_at_section(self):
+        self._doc.seek_next_non_empty_line()
+
+        if self._doc.eof():
+            return False
+
+        l1 = self._doc.peek().strip()  # e.g. Parameters
+
+        if l1.startswith('.. index::'):
+            return True
+
+        l2 = self._doc.peek(1).strip() #    ---------- or ==========
+        return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
+
+    def _strip(self,doc):
+        i = 0
+        j = 0
+        for i,line in enumerate(doc):
+            if line.strip(): break
+
+        for j,line in enumerate(doc[::-1]):
+            if line.strip(): break
+
+        return doc[i:len(doc)-j]
+
+    def _read_to_next_section(self):
+        section = self._doc.read_to_next_empty_line()
+
+        while not self._is_at_section() and not self._doc.eof():
+            if not self._doc.peek(-1).strip(): # previous line was empty
+                section += ['']
+
+            section += self._doc.read_to_next_empty_line()
+
+        return section
+
+    def _read_sections(self):
+        while not self._doc.eof():
+            data = self._read_to_next_section()
+            name = data[0].strip()
+
+            if name.startswith('..'): # index section
+                yield name, data[1:]
+            elif len(data) < 2:
+                yield StopIteration
+            else:
+                yield name, self._strip(data[2:])
+
+    def _parse_param_list(self,content):
+        r = Reader(content)
+        params = []
+        while not r.eof():
+            header = r.read().strip()
+            if ' : ' in header:
+                arg_name, arg_type = header.split(' : ')[:2]
+            else:
+                arg_name, arg_type = header, ''
+
+            desc = r.read_to_next_unindented_line()
+            desc = dedent_lines(desc)
+
+            params.append((arg_name,arg_type,desc))
+
+        return params
+
+    
+    _name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
+                           r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
+    def _parse_see_also(self, content):
+        """
+        func_name : Descriptive text
+            continued text
+        another_func_name : Descriptive text
+        func_name1, func_name2, :meth:`func_name`, func_name3
+
+        """
+        items = []
+
+        def parse_item_name(text):
+            """Match ':role:`name`' or 'name'"""
+            m = self._name_rgx.match(text)
+            if m:
+                g = m.groups()
+                if g[1] is None:
+                    return g[3], None
+                else:
+                    return g[2], g[1]
+            raise ValueError("%s is not a item name" % text)
+
+        def push_item(name, rest):
+            if not name:
+                return
+            name, role = parse_item_name(name)
+            items.append((name, list(rest), role))
+            del rest[:]
+
+        current_func = None
+        rest = []
+        
+        for line in content:
+            if not line.strip(): continue
+
+            m = self._name_rgx.match(line)
+            if m and line[m.end():].strip().startswith(':'):
+                push_item(current_func, rest)
+                current_func, line = line[:m.end()], line[m.end():]
+                rest = [line.split(':', 1)[1].strip()]
+                if not rest[0]:
+                    rest = []
+            elif not line.startswith(' '):
+                push_item(current_func, rest)
+                current_func = None
+                if ',' in line:
+                    for func in line.split(','):
+                        push_item(func, [])
+                elif line.strip():
+                    current_func = line
+            elif current_func is not None:
+                rest.append(line.strip())
+        push_item(current_func, rest)
+        return items
+
+    def _parse_index(self, section, content):
+        """
+        .. index: default
+           :refguide: something, else, and more
+
+        """
+        def strip_each_in(lst):
+            return [s.strip() for s in lst]
+
+        out = {}
+        section = section.split('::')
+        if len(section) > 1:
+            out['default'] = strip_each_in(section[1].split(','))[0]
+        for line in content:
+            line = line.split(':')
+            if len(line) > 2:
+                out[line[1]] = strip_each_in(line[2].split(','))
+        return out
+    
+    def _parse_summary(self):
+        """Grab signature (if given) and summary"""
+        if self._is_at_section():
+            return
+
+        summary = self._doc.read_to_next_empty_line()
+        summary_str = " ".join([s.strip() for s in summary]).strip()
+        if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str):
+            self['Signature'] = summary_str
+            if not self._is_at_section():
+                self['Summary'] = self._doc.read_to_next_empty_line()
+        else:
+            self['Summary'] = summary
+
+        if not self._is_at_section():
+            self['Extended Summary'] = self._read_to_next_section()
+    
+    def _parse(self):
+        self._doc.reset()
+        self._parse_summary()
+
+        for (section,content) in self._read_sections():
+            if not section.startswith('..'):
+                section = ' '.join([s.capitalize() for s in section.split(' ')])
+            if section in ('Parameters', 'Attributes', 'Methods',
+                           'Returns', 'Raises', 'Warns'):
+                self[section] = self._parse_param_list(content)
+            elif section.startswith('.. index::'):
+                self['index'] = self._parse_index(section, content)
+            elif section == 'See Also':
+                self['See Also'] = self._parse_see_also(content)
+            else:
+                self[section] = content
+
+    # string conversion routines
+
+    def _str_header(self, name, symbol='-'):
+        return [name, len(name)*symbol]
+
+    def _str_indent(self, doc, indent=4):
+        out = []
+        for line in doc:
+            out += [' '*indent + line]
+        return out
+
+    def _str_signature(self):
+        if self['Signature']:
+            return [self['Signature'].replace('*','\*')] + ['']
+        else:
+            return ['']
+
+    def _str_summary(self):
+        if self['Summary']:
+            return self['Summary'] + ['']
+        else:
+            return []
+
+    def _str_extended_summary(self):
+        if self['Extended Summary']:
+            return self['Extended Summary'] + ['']
+        else:
+            return []
+
+    def _str_param_list(self, name):
+        out = []
+        if self[name]:
+            out += self._str_header(name)
+            for param,param_type,desc in self[name]:
+                out += ['%s : %s' % (param, param_type)]
+                out += self._str_indent(desc)
+            out += ['']
+        return out
+
+    def _str_section(self, name):
+        out = []
+        if self[name]:
+            out += self._str_header(name)
+            out += self[name]
+            out += ['']
+        return out
+
+    def _str_see_also(self, func_role):
+        if not self['See Also']: return []
+        out = []
+        out += self._str_header("See Also")
+        last_had_desc = True
+        for func, desc, role in self['See Also']:
+            if role:
+                link = ':%s:`%s`' % (role, func)
+            elif func_role:
+                link = ':%s:`%s`' % (func_role, func)
+            else:
+                link = "`%s`_" % func
+            if desc or last_had_desc:
+                out += ['']
+                out += [link]
+            else:
+                out[-1] += ", %s" % link
+            if desc:
+                out += self._str_indent([' '.join(desc)])
+                last_had_desc = True
+            else:
+                last_had_desc = False
+        out += ['']
+        return out
+
+    def _str_index(self):
+        idx = self['index']
+        out = []
+        out += ['.. index:: %s' % idx.get('default','')]
+        for section, references in idx.iteritems():
+            if section == 'default':
+                continue
+            out += ['   :%s: %s' % (section, ', '.join(references))]
+        return out
+
+    def __str__(self, func_role=''):
+        out = []
+        out += self._str_signature()
+        out += self._str_summary()
+        out += self._str_extended_summary()
+        for param_list in ('Parameters','Returns','Raises'):
+            out += self._str_param_list(param_list)
+        out += self._str_section('Warnings')
+        out += self._str_see_also(func_role)
+        for s in ('Notes','References','Examples'):
+            out += self._str_section(s)
+        out += self._str_index()
+        return '\n'.join(out)
+
+
+def indent(str,indent=4):
+    indent_str = ' '*indent
+    if str is None:
+        return indent_str
+    lines = str.split('\n')
+    return '\n'.join(indent_str + l for l in lines)
+
+def dedent_lines(lines):
+    """Deindent a list of lines maximally"""
+    return textwrap.dedent("\n".join(lines)).split("\n")
+
+def header(text, style='-'):
+    return text + '\n' + style*len(text) + '\n'
+
+
+class FunctionDoc(NumpyDocString):
+    def __init__(self, func, role='func', doc=None):
+        self._f = func
+        self._role = role # e.g. "func" or "meth"
+        if doc is None:
+            doc = inspect.getdoc(func) or ''
+        try:
+            NumpyDocString.__init__(self, doc)
+        except ValueError, e:
+            print '*'*78
+            print "ERROR: '%s' while parsing `%s`" % (e, self._f)
+            print '*'*78
+            #print "Docstring follows:"
+            #print doclines
+            #print '='*78
+
+        if not self['Signature']:
+            func, func_name = self.get_func()
+            try:
+                # try to read signature
+                argspec = inspect.getargspec(func)
+                argspec = inspect.formatargspec(*argspec)
+                argspec = argspec.replace('*','\*')
+                signature = '%s%s' % (func_name, argspec)
+            except TypeError, e:
+                signature = '%s()' % func_name
+            self['Signature'] = signature
+
+    def get_func(self):
+        func_name = getattr(self._f, '__name__', self.__class__.__name__)
+        if inspect.isclass(self._f):
+            func = getattr(self._f, '__call__', self._f.__init__)
+        else:
+            func = self._f
+        return func, func_name
+            
+    def __str__(self):
+        out = ''
+
+        func, func_name = self.get_func()
+        signature = self['Signature'].replace('*', '\*')
+
+        roles = {'func': 'function',
+                 'meth': 'method'}
+
+        if self._role:
+            if not roles.has_key(self._role):
+                print "Warning: invalid role %s" % self._role
+            out += '.. %s:: %s\n    \n\n' % (roles.get(self._role,''),
+                                             func_name)
+
+        out += super(FunctionDoc, self).__str__(func_role=self._role)
+        return out
+
+
+class ClassDoc(NumpyDocString):
+    def __init__(self,cls,modulename='',func_doc=FunctionDoc,doc=None):
+        if not inspect.isclass(cls):
+            raise ValueError("Initialise using a class. Got %r" % cls)
+        self._cls = cls
+
+        if modulename and not modulename.endswith('.'):
+            modulename += '.'
+        self._mod = modulename
+        self._name = cls.__name__
+        self._func_doc = func_doc
+
+        if doc is None:
+            doc = pydoc.getdoc(cls)
+
+        NumpyDocString.__init__(self, doc)
+
+    @property
+    def methods(self):
+        return [name for name,func in inspect.getmembers(self._cls)
+                if not name.startswith('_') and callable(func)]
+
+    def __str__(self):
+        out = ''
+        out += super(ClassDoc, self).__str__()
+        out += "\n\n"
+
+        #for m in self.methods:
+        #    print "Parsing `%s`" % m
+        #    out += str(self._func_doc(getattr(self._cls,m), 'meth')) + '\n\n'
+        #    out += '.. index::\n   single: %s; %s\n\n' % (self._name, m)
+
+        return out
+
+

docs/sphinxext/docscrape_sphinx.py

@@ -0,0 +1,136 b''
+import re, inspect, textwrap, pydoc
+from docscrape import NumpyDocString, FunctionDoc, ClassDoc
+
+class SphinxDocString(NumpyDocString):
+    # string conversion routines
+    def _str_header(self, name, symbol='`'):
+        return ['.. rubric:: ' + name, '']
+
+    def _str_field_list(self, name):
+        return [':' + name + ':']
+
+    def _str_indent(self, doc, indent=4):
+        out = []
+        for line in doc:
+            out += [' '*indent + line]
+        return out
+
+    def _str_signature(self):
+        return ['']
+        if self['Signature']:
+            return ['``%s``' % self['Signature']] + ['']
+        else:
+            return ['']
+
+    def _str_summary(self):
+        return self['Summary'] + ['']
+
+    def _str_extended_summary(self):
+        return self['Extended Summary'] + ['']
+
+    def _str_param_list(self, name):
+        out = []
+        if self[name]:
+            out += self._str_field_list(name)
+            out += ['']
+            for param,param_type,desc in self[name]:
+                out += self._str_indent(['**%s** : %s' % (param.strip(),
+                                                          param_type)])
+                out += ['']
+                out += self._str_indent(desc,8)
+                out += ['']
+        return out
+
+    def _str_section(self, name):
+        out = []
+        if self[name]:
+            out += self._str_header(name)
+            out += ['']
+            content = textwrap.dedent("\n".join(self[name])).split("\n")
+            out += content
+            out += ['']
+        return out
+
+    def _str_see_also(self, func_role):
+        out = []
+        if self['See Also']:
+            see_also = super(SphinxDocString, self)._str_see_also(func_role)
+            out = ['.. seealso::', '']
+            out += self._str_indent(see_also[2:])
+        return out
+
+    def _str_warnings(self):
+        out = []
+        if self['Warnings']:
+            out = ['.. warning::', '']
+            out += self._str_indent(self['Warnings'])
+        return out
+
+    def _str_index(self):
+        idx = self['index']
+        out = []
+        if len(idx) == 0:
+            return out
+
+        out += ['.. index:: %s' % idx.get('default','')]
+        for section, references in idx.iteritems():
+            if section == 'default':
+                continue
+            elif section == 'refguide':
+                out += ['   single: %s' % (', '.join(references))]
+            else:
+                out += ['   %s: %s' % (section, ','.join(references))]
+        return out
+
+    def _str_references(self):
+        out = []
+        if self['References']:
+            out += self._str_header('References')
+            if isinstance(self['References'], str):
+                self['References'] = [self['References']]
+            out.extend(self['References'])
+            out += ['']
+        return out
+
+    def __str__(self, indent=0, func_role="obj"):
+        out = []
+        out += self._str_signature()
+        out += self._str_index() + ['']
+        out += self._str_summary()
+        out += self._str_extended_summary()
+        for param_list in ('Parameters', 'Attributes', 'Methods',
+                           'Returns','Raises'):
+            out += self._str_param_list(param_list)
+        out += self._str_warnings()
+        out += self._str_see_also(func_role)
+        out += self._str_section('Notes')
+        out += self._str_references()
+        out += self._str_section('Examples')
+        out = self._str_indent(out,indent)
+        return '\n'.join(out)
+
+class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
+    pass
+
+class SphinxClassDoc(SphinxDocString, ClassDoc):
+    pass
+
+def get_doc_object(obj, what=None, doc=None):
+    if what is None:
+        if inspect.isclass(obj):
+            what = 'class'
+        elif inspect.ismodule(obj):
+            what = 'module'
+        elif callable(obj):
+            what = 'function'
+        else:
+            what = 'object'
+    if what == 'class':
+        return SphinxClassDoc(obj, '', func_doc=SphinxFunctionDoc, doc=doc)
+    elif what in ('function', 'method'):
+        return SphinxFunctionDoc(obj, '', doc=doc)
+    else:
+        if doc is None:
+            doc = pydoc.getdoc(obj)
+        return SphinxDocString(doc)
+

docs/sphinxext/numpydoc.py

@@ -0,0 +1,116 b''
+"""
+========
+numpydoc
+========
+
+Sphinx extension that handles docstrings in the Numpy standard format. [1]
+
+It will:
+
+- Convert Parameters etc. sections to field lists.
+- Convert See Also section to a See also entry.
+- Renumber references.
+- Extract the signature from the docstring, if it can't be determined otherwise.
+
+.. [1] http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#docstring-standard
+
+"""
+
+import os, re, pydoc
+from docscrape_sphinx import get_doc_object, SphinxDocString
+import inspect
+
+def mangle_docstrings(app, what, name, obj, options, lines,
+                      reference_offset=[0]):
+    if what == 'module':
+        # Strip top title
+        title_re = re.compile(r'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
+                              re.I|re.S)
+        lines[:] = title_re.sub('', "\n".join(lines)).split("\n")
+    else:
+        doc = get_doc_object(obj, what, "\n".join(lines))
+        lines[:] = str(doc).split("\n")
+
+    if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
+           obj.__name__:
+        if hasattr(obj, '__module__'):
+            v = dict(full_name="%s.%s" % (obj.__module__, obj.__name__))
+        else:
+            v = dict(full_name=obj.__name__)
+        lines += ['', '.. htmlonly::', '']
+        lines += ['    %s' % x for x in
+                  (app.config.numpydoc_edit_link % v).split("\n")]
+
+    # replace reference numbers so that there are no duplicates
+    references = []
+    for l in lines:
+        l = l.strip()
+        if l.startswith('.. ['):
+            try:
+                references.append(int(l[len('.. ['):l.index(']')]))
+            except ValueError:
+                print "WARNING: invalid reference in %s docstring" % name
+
+    # Start renaming from the biggest number, otherwise we may
+    # overwrite references.
+    references.sort()
+    if references:
+        for i, line in enumerate(lines):
+            for r in references:
+                new_r = reference_offset[0] + r
+                lines[i] = lines[i].replace('[%d]_' % r,
+                                            '[%d]_' % new_r)
+                lines[i] = lines[i].replace('.. [%d]' % r,
+                                            '.. [%d]' % new_r)
+
+    reference_offset[0] += len(references)
+
+def mangle_signature(app, what, name, obj, options, sig, retann):
+    # Do not try to inspect classes that don't define `__init__`
+    if (inspect.isclass(obj) and
+        'initializes x; see ' in pydoc.getdoc(obj.__init__)):
+        return '', ''
+
+    if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return
+    if not hasattr(obj, '__doc__'): return
+
+    doc = SphinxDocString(pydoc.getdoc(obj))
+    if doc['Signature']:
+        sig = re.sub("^[^(]*", "", doc['Signature'])
+        return sig, ''
+
+def initialize(app):
+    try:
+        app.connect('autodoc-process-signature', mangle_signature)
+    except:
+        monkeypatch_sphinx_ext_autodoc()
+
+def setup(app, get_doc_object_=get_doc_object):
+    global get_doc_object
+    get_doc_object = get_doc_object_
+    
+    app.connect('autodoc-process-docstring', mangle_docstrings)
+    app.connect('builder-inited', initialize)
+    app.add_config_value('numpydoc_edit_link', None, True)
+
+#------------------------------------------------------------------------------
+# Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5)
+#------------------------------------------------------------------------------
+
+def monkeypatch_sphinx_ext_autodoc():
+    global _original_format_signature
+    import sphinx.ext.autodoc
+
+    if sphinx.ext.autodoc.format_signature is our_format_signature:
+        return
+
+    print "[numpydoc] Monkeypatching sphinx.ext.autodoc ..."
+    _original_format_signature = sphinx.ext.autodoc.format_signature
+    sphinx.ext.autodoc.format_signature = our_format_signature
+
+def our_format_signature(what, obj):
+    r = mangle_signature(None, what, None, obj, None, None, None)
+    if r is not None:
+        return r[0]
+    else:
+        return _original_format_signature(what, obj)

IPython/completer.py

@@ -6,7 +6,6 b' upstream and were accepted as of Python 2.3, but we need a lot more'
 functionality specific to IPython, so this module will continue to live as an
 IPython-specific utility.
 
----------------------------------------------------------------------------
 Original rlcompleter documentation:
 
 This requires the latest extension to the readline module (the

IPython/genutils.py

@@ -1234,11 +1234,11 b' def esc_quotes(strng):'
 def make_quoted_expr(s):
     """Return string s in appropriate quotes, using raw string if possible.
 
-    Effectively this turns string: cd \ao\ao\
-    to: r"cd \ao\ao\_"[:-1]
-
-    Note the use of raw string and padding at the end to allow trailing backslash.
+    XXX - example removed because it caused encoding errors in documentation
+    generation.  We need a new example that doesn't contain invalid chars.
 
+    Note the use of raw string and padding at the end to allow trailing
+    backslash.
     """
 
     tail = ''

IPython/ipapi.py

@@ -24,7 +24,6 b' That way the module is imported at startup and you can have all your'
 personal configuration (as opposed to boilerplate ipythonrc-PROFILENAME 
 stuff) in there. 
 
------------------------------------------------
 import IPython.ipapi
 ip = IPython.ipapi.get()
 

IPython/kernel/core/util.py

@@ -70,8 +70,8 b' def esc_quotes(strng):'
 def make_quoted_expr(s):
     """Return string s in appropriate quotes, using raw string if possible.
     
-    Effectively this turns string: cd \ao\ao\
-    to: r"cd \ao\ao\_"[:-1]
+    XXX - example removed because it caused encoding errors in documentation
+    generation.  We need a new example that doesn't contain invalid chars.
     
     Note the use of raw string and padding at the end to allow trailing
     backslash.

IPython/testing/decorators.py

@@ -121,7 +121,7 b' def skipif(skip_condition, msg=None):'
     ''' Make function raise SkipTest exception if skip_condition is true
 
     Parameters
-    ---------
+    ----------
     skip_condition : bool or callable. 
  	Flag to determine whether to skip test.  If the condition is a 
  	callable, it is used at runtime to dynamically make the decision.  This 

IPython/testing/decorators_numpy.py

@@ -50,7 +50,7 b' def skipif(skip_condition=True, msg=None):'
     ''' Make function raise SkipTest exception if skip_condition is true
 
     Parameters
-    ---------
+    ----------
     skip_condition : bool or callable. 
  	Flag to determine whether to skip test.  If the condition is a 
  	callable, it is used at runtime to dynamically make the decision.  This 

docs/Makefile

@@ -5,13 +5,14 b''
 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) source
+ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -28,7 +29,7 b' help:'
 	@echo "dist         all, and then puts the results in dist/"
 
 clean:
-	-rm -rf build/* dist/*
+	-rm -rf build/* dist/* $(SRCDIR)/api/generated
 
 pdf: latex
 	cd build/latex && make all-pdf
@@ -41,12 +42,16 b' dist: clean all'
 	cp -al build/html dist/
 	@echo "Build finished.  Final docs are in dist/"
 
-html:
+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:
+	python autogen_api.py
+	@echo "Build API docs finished."
+
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle

docs/source/conf.py

@@ -36,9 +36,13 b" execfile('../../IPython/Release.py',iprelease)"
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
-              'inheritance_diagram', 'only_directives',
+              'sphinx.ext.doctest',
+              
+              'only_directives',
+              'inheritance_diagram',
               'ipython_console_highlighting', 
               # 'plot_directive', # disabled for now, needs matplotlib
+              'numpydoc',  # to preprocess docstrings
               ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/index.txt

@@ -17,10 +17,11 b' IPython Documentation'
    interactive/index.txt
    parallel/index.txt
    config/index.txt
-   changes.txt
-   development/index.txt
    faq.txt
    history.txt
+   changes.txt
+   development/index.txt
+   api/index.txt
    license_and_copyright.txt
    credits.txt
 

docs/source/interactive/reference.txt

@@ -496,9 +496,9 b' following example defines a new magic command, %impall::'
     ip.expose_magic('impall', doimp)
 
 You can also define your own aliased names for magic functions. In your
-ipythonrc file, placing a line like:
+ipythonrc file, placing a line like::
 
-execute __IP.magic_cl = __IP.magic_clear
+    execute __IP.magic_cl = __IP.magic_clear
 
 will define %cl as a new name for %clear.
 
@@ -508,1572 +508,9 b' magic functions at any time and their docstrings. You can also type'
 information on the '?' system) to get information about any particular
 magic function you are interested in.
 
+The API documentation for the :mod:`IPython.Magic` module contains the full
+docstrings of all currently available magic commands.
 
-Magic commands
---------------
-
-The rest of this section is automatically generated for each release
-from the docstrings in the IPython code. Therefore the formatting is
-somewhat minimal, but this method has the advantage of having
-information always in sync with the code.
-
-A list of all the magic commands available in IPython's default
-installation follows. This is similar to what you'll see by simply
-typing %magic at the prompt, but that will also give you information
-about magic commands you may have added as part of your personal
-customizations.
-
-.. magic_start
-
-**%Exit**::
-
-	Exit IPython without confirmation.
-
-**%Pprint**::
-
-	Toggle pretty printing on/off.
-
-**%alias**::
-
-	Define an alias for a system command.
-
-        '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
-
-        Then, typing 'alias_name params' will execute the system command 'cmd
-        params' (from your underlying operating system).
-
-        Aliases have lower precedence than magic functions and Python normal
-        variables, so if 'foo' is both a Python variable and an alias, the
-        alias can not be executed until 'del foo' removes the Python variable.
-
-        You can use the %l specifier in an alias definition to represent the
-        whole line when the alias is called.  For example:
-
-          In [2]: alias all echo "Input in brackets: <%l>"\
-          In [3]: all hello world\
-          Input in brackets: <hello world>
-
-        You can also define aliases with parameters using %s specifiers (one
-        per parameter):
-        
-          In [1]: alias parts echo first %s second %s\
-          In [2]: %parts A B\
-          first A second B\
-          In [3]: %parts A\
-          Incorrect number of arguments: 2 expected.\
-          parts is an alias to: 'echo first %s second %s'
-
-        Note that %l and %s are mutually exclusive.  You can only use one or
-        the other in your aliases.
-
-        Aliases expand Python variables just like system calls using ! or !! 
-        do: all expressions prefixed with '$' get expanded.  For details of
-        the semantic rules, see PEP-215:
-        http://www.python.org/peps/pep-0215.html.  This is the library used by
-        IPython for variable expansion.  If you want to access a true shell
-        variable, an extra $ is necessary to prevent its expansion by IPython:
-
-        In [6]: alias show echo\
-        In [7]: PATH='A Python string'\
-        In [8]: show $PATH\
-        A Python string\
-        In [9]: show $$PATH\
-        /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
-
-        You can use the alias facility to acess all of $PATH.  See the %rehash
-        and %rehashx functions, which automatically create aliases for the
-        contents of your $PATH.
-
-        If called with no parameters, %alias prints the current alias table.
-
-**%autocall**::
-
-	Make functions callable without having to type parentheses.
-
-        Usage:
-
-           %autocall [mode]
-
-        The mode can be one of: 0->Off, 1->Smart, 2->Full.  If not given, the
-        value is toggled on and off (remembering the previous state).
-
-        In more detail, these values mean:
-
-        0 -> fully disabled
-
-        1 -> active, but do not apply if there are no arguments on the line.
-
-        In this mode, you get:
-
-        In [1]: callable
-        Out[1]: <built-in function callable>
-
-        In [2]: callable 'hello'
-        ------> callable('hello')
-        Out[2]: False
-
-        2 -> Active always.  Even if no arguments are present, the callable
-        object is called:
-
-        In [4]: callable
-        ------> callable()
-
-        Note that even with autocall off, you can still use '/' at the start of
-        a line to treat the first argument on the command line as a function
-        and add parentheses to it:
-
-        In [8]: /str 43
-        ------> str(43)
-        Out[8]: '43'
-
-**%autoindent**::
-
-	Toggle autoindent on/off (if available).
-
-**%automagic**::
-
-	Make magic functions callable without having to type the initial %.
-
-        Without argumentsl toggles on/off (when off, you must call it as
-        %automagic, of course).  With arguments it sets the value, and you can
-        use any of (case insensitive):
-
-         - on,1,True: to activate
-
-         - off,0,False: to deactivate.
-
-        Note that magic functions have lowest priority, so if there's a
-        variable whose name collides with that of a magic fn, automagic won't
-        work for that function (you get the variable instead). However, if you
-        delete the variable (del var), the previously shadowed magic function
-        becomes visible to automagic again.
-
-**%bg**::
-
-	Run a job in the background, in a separate thread.
-
-        For example,
-
-          %bg myfunc(x,y,z=1)
-
-        will execute 'myfunc(x,y,z=1)' in a background thread.  As soon as the
-        execution starts, a message will be printed indicating the job
-        number.  If your job number is 5, you can use
-
-          myvar = jobs.result(5)  or  myvar = jobs[5].result
-
-        to assign this result to variable 'myvar'.
-
-        IPython has a job manager, accessible via the 'jobs' object.  You can
-        type jobs? to get more information about it, and use jobs.<TAB> to see
-        its attributes.  All attributes not starting with an underscore are
-        meant for public use.
-
-        In particular, look at the jobs.new() method, which is used to create
-        new jobs.  This magic %bg function is just a convenience wrapper
-        around jobs.new(), for expression-based jobs.  If you want to create a
-        new job with an explicit function object and arguments, you must call
-        jobs.new() directly.
-
-        The jobs.new docstring also describes in detail several important
-        caveats associated with a thread-based model for background job
-        execution.  Type jobs.new? for details.
-
-        You can check the status of all jobs with jobs.status().
-
-        The jobs variable is set by IPython into the Python builtin namespace.
-        If you ever declare a variable named 'jobs', you will shadow this
-        name.  You can either delete your global jobs variable to regain
-        access to the job manager, or make a new name and assign it manually
-        to the manager (stored in IPython's namespace).  For example, to
-        assign the job manager to the Jobs name, use:
-
-          Jobs = __builtins__.jobs
-
-**%bookmark**::
-
-	Manage IPython's bookmark system.
-
-        %bookmark <name>       - set bookmark to current dir
-        %bookmark <name> <dir> - set bookmark to <dir>
-        %bookmark -l           - list all bookmarks
-        %bookmark -d <name>    - remove bookmark
-        %bookmark -r           - remove all bookmarks
-
-        You can later on access a bookmarked folder with:
-          %cd -b <name>
-        or simply '%cd <name>' if there is no directory called <name> AND
-        there is such a bookmark defined.
-
-        Your bookmarks persist through IPython sessions, but they are
-        associated with each profile.
-
-**%cd**::
-
-	Change the current working directory.
-
-        This command automatically maintains an internal list of directories
-        you visit during your IPython session, in the variable _dh. The
-        command %dhist shows this history nicely formatted. You can also
-        do 'cd -<tab>' to see directory history conveniently.
-
-        Usage:
-
-          cd 'dir': changes to directory 'dir'.
-
-          cd -: changes to the last visited directory.
-
-          cd -<n>: changes to the n-th directory in the directory history.
-
-          cd -b <bookmark_name>: jump to a bookmark set by %bookmark
-             (note: cd <bookmark_name> is enough if there is no
-              directory <bookmark_name>, but a bookmark with the name exists.)
-              'cd -b <tab>' allows you to tab-complete bookmark names. 
-
-        Options:
-
-        -q: quiet.  Do not print the working directory after the cd command is
-        executed.  By default IPython's cd command does print this directory,
-        since the default prompts do not display path information.
-        
-        Note that !cd doesn't work for this purpose because the shell where
-        !command runs is immediately discarded after executing 'command'.
-
-**%clear**::
-
-	 Clear various data (e.g. stored history data)
-    
-    %clear out - clear output history
-    %clear in  - clear input history
-    %clear shadow_compress - Compresses shadow history (to speed up ipython)
-    %clear shadow_nuke - permanently erase all entries in shadow history
-    %clear dhist - clear dir history
-
-**%color_info**::
-
-	Toggle color_info.
-
-        The color_info configuration parameter controls whether colors are
-        used for displaying object details (by things like %psource, %pfile or
-        the '?' system). This function toggles this value with each call.
-
-        Note that unless you have a fairly recent pager (less works better
-        than more) in your system, using colored object information displays
-        will not work properly. Test it and see.
-
-**%colors**::
-
-	Switch color scheme for prompts, info system and exception handlers.
-
-        Currently implemented schemes: NoColor, Linux, LightBG.
-
-        Color scheme names are not case-sensitive.
-
-**%cpaste**::
-
-	Allows you to paste & execute a pre-formatted code block from clipboard
-        
-        You must terminate the block with '--' (two minus-signs) alone on the
-        line. You can also provide your own sentinel with '%paste -s %%' ('%%' 
-        is the new sentinel for this operation)
-        
-        The block is dedented prior to execution to enable execution of method
-        definitions. '>' and '+' characters at the beginning of a line are
-        ignored, to allow pasting directly from e-mails or diff files. The
-        executed block is also assigned to variable named 'pasted_block' for
-        later editing with '%edit pasted_block'.
-        
-        You can also pass a variable name as an argument, e.g. '%cpaste foo'.
-        This assigns the pasted block to variable 'foo' as string, without 
-        dedenting or executing it.
-        
-        Do not be alarmed by garbled output on Windows (it's a readline bug). 
-        Just press enter and type -- (and press enter again) and the block 
-        will be what was just pasted.
-        
-        IPython statements (magics, shell escapes) are not supported (yet).
-
-**%debug**::
-
-	Activate the interactive debugger in post-mortem mode.
-
-        If an exception has just occurred, this lets you inspect its stack
-        frames interactively.  Note that this will always work only on the last
-        traceback that occurred, so you must call this quickly after an
-        exception that you wish to inspect has fired, because if another one
-        occurs, it clobbers the previous one.
-
-        If you want IPython to automatically do this on every exception, see
-        the %pdb magic for more details.
-
-**%dhist**::
-
-	Print your history of visited directories.
-
-        %dhist       -> print full history\
-        %dhist n     -> print last n entries only\
-        %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\
-
-        This history is automatically maintained by the %cd command, and
-        always available as the global list variable _dh. You can use %cd -<n>
-        to go to directory number <n>.
-        
-        Note that most of time, you should view directory history by entering
-        cd -<TAB>.
-
-**%dirs**::
-
-	Return the current directory stack.
-
-**%doctest_mode**::
-
-	Toggle doctest mode on and off.
-
-        This mode allows you to toggle the prompt behavior between normal
-        IPython prompts and ones that are as similar to the default IPython
-        interpreter as possible.
-
-        It also supports the pasting of code snippets that have leading '>>>'
-        and '...' prompts in them.  This means that you can paste doctests from
-        files or docstrings (even if they have leading whitespace), and the
-        code will execute correctly.  You can then use '%history -tn' to see
-        the translated history without line numbers; this will give you the
-        input after removal of all the leading prompts and whitespace, which
-        can be pasted back into an editor.
-
-        With these features, you can switch into this mode easily whenever you
-        need to do testing and changes to doctests, without having to leave
-        your existing IPython session.
-
-**%ed**::
-
-	Alias to %edit.
-
-**%edit**::
-
-	Bring up an editor and execute the resulting code.
-
-        Usage:
-          %edit [options] [args]
-
-        %edit runs IPython's editor hook.  The default version of this hook is
-        set to call the __IPYTHON__.rc.editor command.  This is read from your
-        environment variable $EDITOR.  If this isn't found, it will default to
-        vi under Linux/Unix and to notepad under Windows.  See the end of this
-        docstring for how to change the editor hook.
-
-        You can also set the value of this editor via the command line option
-        '-editor' or in your ipythonrc file. This is useful if you wish to use
-        specifically for IPython an editor different from your typical default
-        (and for Windows users who typically don't set environment variables).
-
-        This command allows you to conveniently edit multi-line code right in
-        your IPython session.
-        
-        If called without arguments, %edit opens up an empty editor with a
-        temporary file and will execute the contents of this file when you
-        close it (don't forget to save it!).
-
-
-        Options:
-
-        -n <number>: open the editor at a specified line number.  By default,
-        the IPython editor hook uses the unix syntax 'editor +N filename', but
-        you can configure this by providing your own modified hook if your
-        favorite editor supports line-number specifications with a different
-        syntax.
-        
-        -p: this will call the editor with the same data as the previous time
-        it was used, regardless of how long ago (in your current session) it
-        was.
-
-        -r: use 'raw' input.  This option only applies to input taken from the
-        user's history.  By default, the 'processed' history is used, so that
-        magics are loaded in their transformed version to valid Python.  If
-        this option is given, the raw input as typed as the command line is
-        used instead.  When you exit the editor, it will be executed by
-        IPython's own processor.
-        
-        -x: do not execute the edited code immediately upon exit. This is
-        mainly useful if you are editing programs which need to be called with
-        command line arguments, which you can then do using %run.
-
-
-        Arguments:
-
-        If arguments are given, the following possibilites exist:
-
-        - The arguments are numbers or pairs of colon-separated numbers (like
-        1 4:8 9). These are interpreted as lines of previous input to be
-        loaded into the editor. The syntax is the same of the %macro command.
-
-        - If the argument doesn't start with a number, it is evaluated as a
-        variable and its contents loaded into the editor. You can thus edit
-        any string which contains python code (including the result of
-        previous edits).
-
-        - If the argument is the name of an object (other than a string),
-        IPython will try to locate the file where it was defined and open the
-        editor at the point where it is defined. You can use `%edit function`
-        to load an editor exactly at the point where 'function' is defined,
-        edit it and have the file be executed automatically.
-
-        If the object is a macro (see %macro for details), this opens up your
-        specified editor with a temporary file containing the macro's data.
-        Upon exit, the macro is reloaded with the contents of the file.
-
-        Note: opening at an exact line is only supported under Unix, and some
-        editors (like kedit and gedit up to Gnome 2.8) do not understand the
-        '+NUMBER' parameter necessary for this feature. Good editors like
-        (X)Emacs, vi, jed, pico and joe all do.
-
-        - If the argument is not found as a variable, IPython will look for a
-        file with that name (adding .py if necessary) and load it into the
-        editor. It will execute its contents with execfile() when you exit,
-        loading any code in the file into your interactive namespace.
-
-        After executing your code, %edit will return as output the code you
-        typed in the editor (except when it was an existing file). This way
-        you can reload the code in further invocations of %edit as a variable,
-        via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
-        the output.
-
-        Note that %edit is also available through the alias %ed.
-
-        This is an example of creating a simple function inside the editor and
-        then modifying it. First, start up the editor:
-
-        In [1]: ed\
-        Editing... done. Executing edited code...\
-        Out[1]: 'def foo():\n    print "foo() was defined in an editing session"\n'
-
-        We can then call the function foo():
-        
-        In [2]: foo()\
-        foo() was defined in an editing session
-
-        Now we edit foo.  IPython automatically loads the editor with the
-        (temporary) file where foo() was previously defined:
-        
-        In [3]: ed foo\
-        Editing... done. Executing edited code...
-
-        And if we call foo() again we get the modified version:
-        
-        In [4]: foo()\
-        foo() has now been changed!
-
-        Here is an example of how to edit a code snippet successive
-        times. First we call the editor:
-
-        In [8]: ed\
-        Editing... done. Executing edited code...\
-        hello\
-        Out[8]: "print 'hello'\n"
-
-        Now we call it again with the previous output (stored in _):
-
-        In [9]: ed _\
-        Editing... done. Executing edited code...\
-        hello world\
-        Out[9]: "print 'hello world'\n"
-
-        Now we call it with the output #8 (stored in _8, also as Out[8]):
-
-        In [10]: ed _8\
-        Editing... done. Executing edited code...\
-        hello again\
-        Out[10]: "print 'hello again'\n"
-
-
-        Changing the default editor hook:
-
-        If you wish to write your own editor hook, you can put it in a
-        configuration file which you load at startup time.  The default hook
-        is defined in the IPython.hooks module, and you can use that as a
-        starting example for further modifications.  That file also has
-        general instructions on how to set a new hook for use once you've
-        defined it.
-
-**%env**::
-
-	List environment variables.
-
-**%exit**::
-
-	Exit IPython, confirming if configured to do so.
-
-        You can configure whether IPython asks for confirmation upon exit by
-        setting the confirm_exit flag in the ipythonrc file.
-
-**%hist**::
-
-	Alternate name for %history.
-
-**%history**::
-
-	Print input history (_i<n> variables), with most recent last.
-    
-    %history       -> print at most 40 inputs (some may be multi-line)\
-    %history n     -> print at most n inputs\
-    %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\
-    
-    Each input's number <n> is shown, and is accessible as the
-    automatically generated variable _i<n>.  Multi-line statements are
-    printed starting at a new line for easy copy/paste.
-    
-
-    Options:
-
-      -n: do NOT print line numbers. This is useful if you want to get a
-      printout of many lines which can be directly pasted into a text
-      editor.
-
-      This feature is only available if numbered prompts are in use.
-
-      -t: (default) print the 'translated' history, as IPython understands it.
-      IPython filters your input and converts it all into valid Python source
-      before executing it (things like magics or aliases are turned into
-      function calls, for example). With this option, you'll see the native
-      history instead of the user-entered version: '%cd /' will be seen as
-      '_ip.magic("%cd /")' instead of '%cd /'.
-      
-      -r: print the 'raw' history, i.e. the actual commands you typed.
-      
-      -g: treat the arg as a pattern to grep for in (full) history.
-      This includes the "shadow history" (almost all commands ever written).
-      Use '%hist -g' to show full shadow history (may be very long).
-      In shadow history, every index nuwber starts with 0.
-
-      -f FILENAME: instead of printing the output to the screen, redirect it to
-       the given file.  The file is always overwritten, though IPython asks for
-       confirmation first if it already exists.
-
-**%logoff**::
-
-	Temporarily stop logging.
-
-        You must have previously started logging.
-
-**%logon**::
-
-	Restart logging.
-
-        This function is for restarting logging which you've temporarily
-        stopped with %logoff. For starting logging for the first time, you
-        must use the %logstart function, which allows you to specify an
-        optional log filename.
-
-**%logstart**::
-
-	Start logging anywhere in a session.
-
-        %logstart [-o|-r|-t] [log_name [log_mode]]
-
-        If no name is given, it defaults to a file named 'ipython_log.py' in your
-        current directory, in 'rotate' mode (see below).
-
-        '%logstart name' saves to file 'name' in 'backup' mode.  It saves your
-        history up to that point and then continues logging.
-
-        %logstart takes a second optional parameter: logging mode. This can be one
-        of (note that the modes are given unquoted):\
-          append: well, that says it.\
-          backup: rename (if exists) to name~ and start name.\
-          global: single logfile in your home dir, appended to.\
-          over  : overwrite existing log.\
-          rotate: create rotating logs name.1~, name.2~, etc.
-
-        Options:
-
-          -o: log also IPython's output.  In this mode, all commands which
-          generate an Out[NN] prompt are recorded to the logfile, right after
-          their corresponding input line.  The output lines are always
-          prepended with a '#[Out]# ' marker, so that the log remains valid
-          Python code.
-
-          Since this marker is always the same, filtering only the output from
-          a log is very easy, using for example a simple awk call:
-
-            awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py
-
-          -r: log 'raw' input.  Normally, IPython's logs contain the processed
-          input, so that user lines are logged in their final form, converted
-          into valid Python.  For example, %Exit is logged as
-          '_ip.magic("Exit").  If the -r flag is given, all input is logged
-          exactly as typed, with no transformations applied.
-
-          -t: put timestamps before each input line logged (these are put in
-          comments).
-
-**%logstate**::
-
-	Print the status of the logging system.
-
-**%logstop**::
-
-	Fully stop logging and close log file.
-
-        In order to start logging again, a new %logstart call needs to be made,
-        possibly (though not necessarily) with a new filename, mode and other
-        options.
-
-**%lsmagic**::
-
-	List currently available magic functions.
-
-**%macro**::
-
-	Define a set of input lines as a macro for future re-execution.
-
-        Usage:\
-          %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
-
-        Options:
-        
-          -r: use 'raw' input.  By default, the 'processed' history is used,
-          so that magics are loaded in their transformed version to valid
-          Python.  If this option is given, the raw input as typed as the
-          command line is used instead.
-
-        This will define a global variable called `name` which is a string
-        made of joining the slices and lines you specify (n1,n2,... numbers
-        above) from your input history into a single string. This variable
-        acts like an automatic function which re-executes those lines as if
-        you had typed them. You just type 'name' at the prompt and the code
-        executes.
-
-        The notation for indicating number ranges is: n1-n2 means 'use line
-        numbers n1,...n2' (the endpoint is included).  That is, '5-7' means
-        using the lines numbered 5,6 and 7.
-
-        Note: as a 'hidden' feature, you can also use traditional python slice
-        notation, where N:M means numbers N through M-1.
-
-        For example, if your history contains (%hist prints it):
-        
-          44: x=1\
-          45: y=3\
-          46: z=x+y\
-          47: print x\
-          48: a=5\
-          49: print 'x',x,'y',y\
-
-        you can create a macro with lines 44 through 47 (included) and line 49
-        called my_macro with:
-
-          In [51]: %macro my_macro 44-47 49
-
-        Now, typing `my_macro` (without quotes) will re-execute all this code
-        in one pass.
-
-        You don't need to give the line-numbers in order, and any given line
-        number can appear multiple times. You can assemble macros with any
-        lines from your input history in any order.
-
-        The macro is a simple object which holds its value in an attribute,
-        but IPython's display system checks for macros and executes them as
-        code instead of printing them when you type their name.
-
-        You can view a macro's contents by explicitly printing it with:
-        
-          'print macro_name'.
-
-        For one-off cases which DON'T contain magic function calls in them you
-        can obtain similar results by explicitly executing slices from your
-        input history with:
-
-          In [60]: exec In[44:48]+In[49]
-
-**%magic**::
-
-	Print information about the magic function system.
-
-**%mglob**::
-
-	    This program allows specifying filenames with "mglob" mechanism.
-    Supported syntax in globs (wilcard matching patterns)::
-    
-     *.cpp ?ellowo*                
-         - obvious. Differs from normal glob in that dirs are not included.
-           Unix users might want to write this as: "*.cpp" "?ellowo*"
-     rec:/usr/share=*.txt,*.doc    
-         - get all *.txt and *.doc under /usr/share, 
-           recursively
-     rec:/usr/share
-         - All files under /usr/share, recursively
-     rec:*.py
-         - All .py files under current working dir, recursively
-     foo                           
-         - File or dir foo
-     !*.bak readme*                   
-         - readme*, exclude files ending with .bak
-     !.svn/ !.hg/ !*_Data/ rec:.
-         - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
-           Trailing / is the key, \ does not work!
-     dir:foo                       
-         - the directory foo if it exists (not files in foo)
-     dir:*                         
-         - all directories in current folder
-     foo.py bar.* !h* rec:*.py
-         - Obvious. !h* exclusion only applies for rec:*.py.
-           foo.py is *not* included twice.
-     @filelist.txt
-         - All files listed in 'filelist.txt' file, on separate lines.
-
-**%page**::
-
-	Pretty print the object and display it through a pager.
-        
-        %page [options] OBJECT
-
-        If no object is given, use _ (last output).
-        
-        Options:
-
-          -r: page str(object), don't pretty-print it.
-
-**%pdb**::
-
-	Control the automatic calling of the pdb interactive debugger.
-
-        Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
-        argument it works as a toggle.
-
-        When an exception is triggered, IPython can optionally call the
-        interactive pdb debugger after the traceback printout. %pdb toggles
-        this feature on and off.
-
-        The initial state of this feature is set in your ipythonrc
-        configuration file (the variable is called 'pdb').
-
-        If you want to just activate the debugger AFTER an exception has fired,
-        without having to type '%pdb on' and rerunning your code, you can use
-        the %debug magic.
-
-**%pdef**::
-
-	Print the definition header for any callable object.
-
-        If the object is a class, print the constructor information.
-
-**%pdoc**::
-
-	Print the docstring for an object.
-
-        If the given object is a class, it will print both the class and the
-        constructor docstrings.
-
-**%pfile**::
-
-	Print (or run through pager) the file where an object is defined.
-
-        The file opens at the line where the object definition begins. IPython
-        will honor the environment variable PAGER if set, and otherwise will
-        do its best to print the file in a convenient form.
-
-        If the given argument is not an object currently defined, IPython will
-        try to interpret it as a filename (automatically adding a .py extension
-        if needed). You can thus use %pfile as a syntax highlighting code
-        viewer.
-
-**%pinfo**::
-
-	Provide detailed information about an object.
-    
-        '%pinfo object' is just a synonym for object? or ?object.
-
-**%popd**::
-
-	Change to directory popped off the top of the stack.
-
-**%profile**::
-
-	Print your currently active IPyhton profile.
-
-**%prun**::
-
-	Run a statement through the python code profiler.
-
-        Usage:\
-          %prun [options] statement
-
-        The given statement (which doesn't require quote marks) is run via the
-        python profiler in a manner similar to the profile.run() function.
-        Namespaces are internally managed to work correctly; profile.run
-        cannot be used in IPython because it makes certain assumptions about
-        namespaces which do not hold under IPython.
-
-        Options:
-
-        -l <limit>: you can place restrictions on what or how much of the
-        profile gets printed. The limit value can be:
-
-          * A string: only information for function names containing this string
-          is printed.
-
-          * An integer: only these many lines are printed.
-
-          * A float (between 0 and 1): this fraction of the report is printed
-          (for example, use a limit of 0.4 to see the topmost 40% only).
-
-        You can combine several limits with repeated use of the option. For
-        example, '-l __init__ -l 5' will print only the topmost 5 lines of
-        information about class constructors.
-
-        -r: return the pstats.Stats object generated by the profiling. This
-        object has all the information about the profile in it, and you can
-        later use it for further analysis or in other functions.
-
-       -s <key>: sort profile by given key. You can provide more than one key
-        by using the option several times: '-s key1 -s key2 -s key3...'. The
-        default sorting key is 'time'.
-
-        The following is copied verbatim from the profile documentation
-        referenced below:
-
-        When more than one key is provided, additional keys are used as
-        secondary criteria when the there is equality in all keys selected
-        before them.
-        
-        Abbreviations can be used for any key names, as long as the
-        abbreviation is unambiguous.  The following are the keys currently
-        defined:
-
-                Valid Arg       Meaning\
-                  "calls"      call count\
-                  "cumulative" cumulative time\
-                  "file"       file name\
-                  "module"     file name\
-                  "pcalls"     primitive call count\
-                  "line"       line number\
-                  "name"       function name\
-                  "nfl"        name/file/line\
-                  "stdname"    standard name\
-                  "time"       internal time
-
-        Note that all sorts on statistics are in descending order (placing
-        most time consuming items first), where as name, file, and line number
-        searches are in ascending order (i.e., alphabetical). The subtle
-        distinction between "nfl" and "stdname" is that the standard name is a
-        sort of the name as printed, which means that the embedded line
-        numbers get compared in an odd way.  For example, lines 3, 20, and 40
-        would (if the file names were the same) appear in the string order
-        "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
-        line numbers.  In fact, sort_stats("nfl") is the same as
-        sort_stats("name", "file", "line").
-
-        -T <filename>: save profile results as shown on screen to a text
-        file. The profile is still shown on screen.
-
-        -D <filename>: save (via dump_stats) profile statistics to given
-        filename. This data is in a format understod by the pstats module, and
-        is generated by a call to the dump_stats() method of profile
-        objects. The profile is still shown on screen.
-
-        If you want to run complete programs under the profiler's control, use
-        '%run -p [prof_opts] filename.py [args to program]' where prof_opts
-        contains profiler specific options as described here.
-        
-        You can read the complete documentation for the profile module with:\
-          In [1]: import profile; profile.help()
-
-**%psearch**::
-
-	Search for object in namespaces by wildcard.
-
-        %psearch [options] PATTERN [OBJECT TYPE]
-
-        Note: ? can be used as a synonym for %psearch, at the beginning or at
-        the end: both a*? and ?a* are equivalent to '%psearch a*'.  Still, the
-        rest of the command line must be unchanged (options come first), so
-        for example the following forms are equivalent
-
-        %psearch -i a* function
-        -i a* function?
-        ?-i a* function
-
-        Arguments:
-        
-          PATTERN
-
-          where PATTERN is a string containing * as a wildcard similar to its
-          use in a shell.  The pattern is matched in all namespaces on the
-          search path. By default objects starting with a single _ are not
-          matched, many IPython generated objects have a single
-          underscore. The default is case insensitive matching. Matching is
-          also done on the attributes of objects and not only on the objects
-          in a module.
-
-          [OBJECT TYPE]
-
-          Is the name of a python type from the types module. The name is
-          given in lowercase without the ending type, ex. StringType is
-          written string. By adding a type here only objects matching the
-          given type are matched. Using all here makes the pattern match all
-          types (this is the default).
-
-        Options:
-
-          -a: makes the pattern match even objects whose names start with a
-          single underscore.  These names are normally ommitted from the
-          search.
-
-          -i/-c: make the pattern case insensitive/sensitive.  If neither of
-          these options is given, the default is read from your ipythonrc
-          file.  The option name which sets this value is
-          'wildcards_case_sensitive'.  If this option is not specified in your
-          ipythonrc file, IPython's internal default is to do a case sensitive
-          search.
-
-          -e/-s NAMESPACE: exclude/search a given namespace.  The pattern you
-          specifiy can be searched in any of the following namespaces:
-          'builtin', 'user', 'user_global','internal', 'alias', where
-          'builtin' and 'user' are the search defaults.  Note that you should
-          not use quotes when specifying namespaces.
-
-          'Builtin' contains the python module builtin, 'user' contains all
-          user data, 'alias' only contain the shell aliases and no python
-          objects, 'internal' contains objects used by IPython.  The
-          'user_global' namespace is only used by embedded IPython instances,
-          and it contains module-level globals.  You can add namespaces to the
-          search with -s or exclude them with -e (these options can be given
-          more than once).
-    
-        Examples:
-       
-        %psearch a*            -> objects beginning with an a
-        %psearch -e builtin a* -> objects NOT in the builtin space starting in a
-        %psearch a* function   -> all functions beginning with an a
-        %psearch re.e*         -> objects beginning with an e in module re
-        %psearch r*.e*         -> objects that start with e in modules starting in r
-        %psearch r*.* string   -> all strings in modules beginning with r
-
-        Case sensitve search:
-       
-        %psearch -c a*         list all object beginning with lower case a
-
-        Show objects beginning with a single _:
-       
-        %psearch -a _*         list objects beginning with a single underscore
-
-**%psource**::
-
-	Print (or run through pager) the source code for an object.
-
-**%pushd**::
-
-	Place the current dir on stack and change directory.
-        
-        Usage:\
-          %pushd ['dirname']
-
-**%pwd**::
-
-	Return the current working directory path.
-
-**%pycat**::
-
-	Show a syntax-highlighted file through a pager.
-
-        This magic is similar to the cat utility, but it will assume the file
-        to be Python source and will show it with syntax highlighting.
-
-**%quickref**::
-
-	 Show a quick reference sheet
-
-**%quit**::
-
-	Exit IPython, confirming if configured to do so (like %exit)
-
-**%r**::
-
-	Repeat previous input.
-
-        Note: Consider using the more powerfull %rep instead!
-        
-        If given an argument, repeats the previous command which starts with
-        the same string, otherwise it just repeats the previous input.
-
-        Shell escaped commands (with ! as first character) are not recognized
-        by this system, only pure python code and magic commands.
-
-**%rehashdir**::
-
-	 Add executables in all specified dirs to alias table
-     
-    Usage:
-
-    %rehashdir c:/bin;c:/tools
-      - Add all executables under c:/bin and c:/tools to alias table, in 
-      order to make them directly executable from any directory.
-        
-      Without arguments, add all executables in current directory.
-
-**%rehashx**::
-
-	Update the alias table with all executable files in $PATH.
-
-        This version explicitly checks that every entry in $PATH is a file
-        with execute access (os.X_OK), so it is much slower than %rehash.
-
-        Under Windows, it checks executability as a match agains a
-        '|'-separated string of extensions, stored in the IPython config
-        variable win_exec_ext.  This defaults to 'exe|com|bat'.
-        
-        This function also resets the root module cache of module completer,
-        used on slow filesystems.
-
-**%rep**::
-
-	 Repeat a command, or get command to input line for editing
-
-    - %rep (no arguments):
-    
-    Place a string version of last computation result (stored in the special '_'
-    variable) to the next input prompt. Allows you to create elaborate command
-    lines without using copy-paste::
-    
-        $ l = ["hei", "vaan"]       
-        $ "".join(l)        
-        ==> heivaan        
-        $ %rep        
-        $ heivaan_ <== cursor blinking    
-    
-    %rep 45
-    
-    Place history line 45 to next input prompt. Use %hist to find out the
-    number.
-    
-    %rep 1-4 6-7 3
-    
-    Repeat the specified lines immediately. Input slice syntax is the same as
-    in %macro and %save.
-    
-    %rep foo
-    
-    Place the most recent line that has the substring "foo" to next input.
-    (e.g. 'svn ci -m foobar').
-
-**%reset**::
-
-	Resets the namespace by removing all names defined by the user.
-
-        Input/Output history are left around in case you need them.
-
-**%run**::
-
-	Run the named file inside IPython as a program.
-
-        Usage:\
-          %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
-        
-        Parameters after the filename are passed as command-line arguments to
-        the program (put in sys.argv). Then, control returns to IPython's
-        prompt.
-
-        This is similar to running at a system prompt:\
-          $ python file args\
-        but with the advantage of giving you IPython's tracebacks, and of
-        loading all variables into your interactive namespace for further use
-        (unless -p is used, see below).
-
-        The file is executed in a namespace initially consisting only of
-        __name__=='__main__' and sys.argv constructed as indicated. It thus
-        sees its environment as if it were being run as a stand-alone program
-        (except for sharing global objects such as previously imported
-        modules). But after execution, the IPython interactive namespace gets
-        updated with all variables defined in the program (except for __name__
-        and sys.argv). This allows for very convenient loading of code for
-        interactive work, while giving each program a 'clean sheet' to run in.
-
-        Options:
-        
-        -n: __name__ is NOT set to '__main__', but to the running file's name
-        without extension (as python does under import).  This allows running
-        scripts and reloading the definitions in them without calling code
-        protected by an ' if __name__ == "__main__" ' clause.
-
-        -i: run the file in IPython's namespace instead of an empty one. This
-        is useful if you are experimenting with code written in a text editor
-        which depends on variables defined interactively.
-
-        -e: ignore sys.exit() calls or SystemExit exceptions in the script
-        being run.  This is particularly useful if IPython is being used to
-        run unittests, which always exit with a sys.exit() call.  In such
-        cases you are interested in the output of the test results, not in
-        seeing a traceback of the unittest module.
-
-        -t: print timing information at the end of the run.  IPython will give
-        you an estimated CPU time consumption for your script, which under
-        Unix uses the resource module to avoid the wraparound problems of
-        time.clock().  Under Unix, an estimate of time spent on system tasks
-        is also given (for Windows platforms this is reported as 0.0).
-
-        If -t is given, an additional -N<N> option can be given, where <N>
-        must be an integer indicating how many times you want the script to
-        run.  The final timing report will include total and per run results.
-
-        For example (testing the script uniq_stable.py):
-
-            In [1]: run -t uniq_stable
-
-            IPython CPU timings (estimated):\
-              User  :    0.19597 s.\
-              System:        0.0 s.\
-
-            In [2]: run -t -N5 uniq_stable
-
-            IPython CPU timings (estimated):\
-            Total runs performed: 5\
-              Times :      Total       Per run\
-              User  :   0.910862 s,  0.1821724 s.\
-              System:        0.0 s,        0.0 s.
-
-        -d: run your program under the control of pdb, the Python debugger.
-        This allows you to execute your program step by step, watch variables,
-        etc.  Internally, what IPython does is similar to calling:
-        
-          pdb.run('execfile("YOURFILENAME")')
-
-        with a breakpoint set on line 1 of your file.  You can change the line
-        number for this automatic breakpoint to be <N> by using the -bN option
-        (where N must be an integer).  For example:
-
-          %run -d -b40 myscript
-
-        will set the first breakpoint at line 40 in myscript.py.  Note that
-        the first breakpoint must be set on a line which actually does
-        something (not a comment or docstring) for it to stop execution.
-
-        When the pdb debugger starts, you will see a (Pdb) prompt.  You must
-        first enter 'c' (without qoutes) to start execution up to the first
-        breakpoint.
-
-        Entering 'help' gives information about the use of the debugger.  You
-        can easily see pdb's full documentation with "import pdb;pdb.help()"
-        at a prompt.
-
-        -p: run program under the control of the Python profiler module (which
-        prints a detailed report of execution times, function calls, etc).
-
-        You can pass other options after -p which affect the behavior of the
-        profiler itself. See the docs for %prun for details.
-
-        In this mode, the program's variables do NOT propagate back to the
-        IPython interactive namespace (because they remain in the namespace
-        where the profiler executes them).
-
-        Internally this triggers a call to %prun, see its documentation for
-        details on the options available specifically for profiling.
-
-        There is one special usage for which the text above doesn't apply:
-        if the filename ends with .ipy, the file is run as ipython script,
-        just as if the commands were written on IPython prompt.
-
-**%runlog**::
-
-	Run files as logs.
-
-        Usage:\
-          %runlog file1 file2 ...
-
-        Run the named files (treating them as log files) in sequence inside
-        the interpreter, and return to the prompt.  This is much slower than
-        %run because each line is executed in a try/except block, but it
-        allows running files with syntax errors in them.
-
-        Normally IPython will guess when a file is one of its own logfiles, so
-        you can typically use %run even for logs. This shorthand allows you to
-        force any file to be treated as a log file.
-
-**%save**::
-
-	Save a set of lines to a given filename.
-
-        Usage:\
-          %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
-
-        Options:
-        
-          -r: use 'raw' input.  By default, the 'processed' history is used,
-          so that magics are loaded in their transformed version to valid
-          Python.  If this option is given, the raw input as typed as the
-          command line is used instead.
-
-        This function uses the same syntax as %macro for line extraction, but
-        instead of creating a macro it saves the resulting string to the
-        filename you specify.
-
-        It adds a '.py' extension to the file if you don't do so yourself, and
-        it asks for confirmation before overwriting existing files.
-
-**%sc**::
-
-	Shell capture - execute a shell command and capture its output.
-
-        DEPRECATED. Suboptimal, retained for backwards compatibility.
-        
-        You should use the form 'var = !command' instead. Example:
-         
-         "%sc -l myfiles = ls ~" should now be written as
-            
-         "myfiles = !ls ~"
-         
-        myfiles.s, myfiles.l and myfiles.n still apply as documented
-        below.
-
-        --
-        %sc [options] varname=command
-
-        IPython will run the given command using commands.getoutput(), and
-        will then update the user's interactive namespace with a variable
-        called varname, containing the value of the call.  Your command can
-        contain shell wildcards, pipes, etc.
-
-        The '=' sign in the syntax is mandatory, and the variable name you
-        supply must follow Python's standard conventions for valid names.
-        
-        (A special format without variable name exists for internal use)
-
-        Options:
-
-          -l: list output.  Split the output on newlines into a list before
-          assigning it to the given variable.  By default the output is stored
-          as a single string.
-
-          -v: verbose.  Print the contents of the variable.
-
-        In most cases you should not need to split as a list, because the
-        returned value is a special type of string which can automatically
-        provide its contents either as a list (split on newlines) or as a
-        space-separated string.  These are convenient, respectively, either
-        for sequential processing or to be passed to a shell command.
-
-        For example:
-
-            # Capture into variable a
-            In [9]: sc a=ls *py
-
-            # a is a string with embedded newlines
-            In [10]: a
-            Out[10]: 'setup.py win32_manual_post_install.py'
-
-            # which can be seen as a list:
-            In [11]: a.l
-            Out[11]: ['setup.py', 'win32_manual_post_install.py']
-
-            # or as a whitespace-separated string:
-            In [12]: a.s
-            Out[12]: 'setup.py win32_manual_post_install.py'
-
-            # a.s is useful to pass as a single command line:
-            In [13]: !wc -l $a.s
-              146 setup.py
-              130 win32_manual_post_install.py
-              276 total
-
-            # while the list form is useful to loop over:
-            In [14]: for f in a.l:
-               ....:      !wc -l $f
-               ....:
-            146 setup.py
-            130 win32_manual_post_install.py
-
-        Similiarly, the lists returned by the -l option are also special, in
-        the sense that you can equally invoke the .s attribute on them to
-        automatically get a whitespace-separated string from their contents:
-
-            In [1]: sc -l b=ls *py
-
-            In [2]: b
-            Out[2]: ['setup.py', 'win32_manual_post_install.py']
-
-            In [3]: b.s
-            Out[3]: 'setup.py win32_manual_post_install.py'
-
-        In summary, both the lists and strings used for ouptut capture have
-        the following special attributes:
-
-            .l (or .list) : value as list.
-            .n (or .nlstr): value as newline-separated string.
-            .s (or .spstr): value as space-separated string.
-
-**%store**::
-
-	Lightweight persistence for python variables.
-
-    Example:
-    
-    ville@badger[~]|1> A = ['hello',10,'world']\
-    ville@badger[~]|2> %store A\
-    ville@badger[~]|3> Exit
-    
-    (IPython session is closed and started again...)
-    
-    ville@badger:~$ ipython -p pysh\
-    ville@badger[~]|1> print A
-    
-    ['hello', 10, 'world']
-    
-    Usage:
-    
-    %store          - Show list of all variables and their current values\
-    %store <var>    - Store the *current* value of the variable to disk\
-    %store -d <var> - Remove the variable and its value from storage\
-    %store -z       - Remove all variables from storage\
-    %store -r       - Refresh all variables from store (delete current vals)\
-    %store foo >a.txt  - Store value of foo to new file a.txt\
-    %store foo >>a.txt - Append value of foo to file a.txt\   
-    
-    It should be noted that if you change the value of a variable, you
-    need to %store it again if you want to persist the new value.
-    
-    Note also that the variables will need to be pickleable; most basic
-    python types can be safely %stored.
-    
-    Also aliases can be %store'd across sessions.
-
-**%sx**::
-
-	Shell execute - run a shell command and capture its output.
-
-        %sx command
-
-        IPython will run the given command using commands.getoutput(), and
-        return the result formatted as a list (split on '\n').  Since the
-        output is _returned_, it will be stored in ipython's regular output
-        cache Out[N] and in the '_N' automatic variables.
-
-        Notes:
-
-        1) If an input line begins with '!!', then %sx is automatically
-        invoked.  That is, while:
-          !ls
-        causes ipython to simply issue system('ls'), typing
-          !!ls
-        is a shorthand equivalent to:
-          %sx ls
-        
-        2) %sx differs from %sc in that %sx automatically splits into a list,
-        like '%sc -l'.  The reason for this is to make it as easy as possible
-        to process line-oriented shell output via further python commands.
-        %sc is meant to provide much finer control, but requires more
-        typing.
-
-        3) Just like %sc -l, this is a list with special attributes:
-
-          .l (or .list) : value as list.
-          .n (or .nlstr): value as newline-separated string.
-          .s (or .spstr): value as whitespace-separated string.
-
-        This is very useful when trying to use such lists as arguments to
-        system commands.
-
-**%system_verbose**::
-
-	Set verbose printing of system calls.
-
-        If called without an argument, act as a toggle
-
-**%time**::
-
-	Time execution of a Python statement or expression.
-
-        The CPU and wall clock times are printed, and the value of the
-        expression (if any) is returned.  Note that under Win32, system time
-        is always reported as 0, since it can not be measured.
-
-        This function provides very basic timing functionality.  In Python
-        2.3, the timeit module offers more control and sophistication, so this
-        could be rewritten to use it (patches welcome).
-        
-        Some examples:
-
-          In [1]: time 2**128
-          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
-          Wall time: 0.00
-          Out[1]: 340282366920938463463374607431768211456L
-
-          In [2]: n = 1000000
-
-          In [3]: time sum(range(n))
-          CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
-          Wall time: 1.37
-          Out[3]: 499999500000L
-
-          In [4]: time print 'hello world'
-          hello world
-          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
-          Wall time: 0.00
-
-          Note that the time needed by Python to compile the given expression
-          will be reported if it is more than 0.1s.  In this example, the
-          actual exponentiation is done by Python at compilation time, so while
-          the expression can take a noticeable amount of time to compute, that
-          time is purely due to the compilation:
-
-          In [5]: time 3**9999;
-          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
-          Wall time: 0.00 s
-
-          In [6]: time 3**999999;
-          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
-          Wall time: 0.00 s
-          Compiler : 0.78 s
-
-**%timeit**::
-
-	Time execution of a Python statement or expression
-
-        Usage:\
-          %timeit [-n<N> -r<R> [-t|-c]] statement
-
-        Time execution of a Python statement or expression using the timeit
-        module.
-
-        Options:
-        -n<N>: execute the given statement <N> times in a loop. If this value
-        is not given, a fitting value is chosen. 
-        
-        -r<R>: repeat the loop iteration <R> times and take the best result.
-        Default: 3
-        
-        -t: use time.time to measure the time, which is the default on Unix.
-        This function measures wall time.
-        
-        -c: use time.clock to measure the time, which is the default on
-        Windows and measures wall time. On Unix, resource.getrusage is used
-        instead and returns the CPU user time.
-
-        -p<P>: use a precision of <P> digits to display the timing result.
-        Default: 3
-
-        
-        Examples:\
-          In [1]: %timeit pass
-          10000000 loops, best of 3: 53.3 ns per loop
-
-          In [2]: u = None
-
-          In [3]: %timeit u is None
-          10000000 loops, best of 3: 184 ns per loop
-
-          In [4]: %timeit -r 4 u == None
-          1000000 loops, best of 4: 242 ns per loop
-
-          In [5]: import time
-
-          In [6]: %timeit -n1 time.sleep(2)
-          1 loops, best of 3: 2 s per loop
-          
-
-        The times reported by %timeit will be slightly higher than those
-        reported by the timeit.py script when variables are accessed. This is
-        due to the fact that %timeit executes the statement in the namespace
-        of the shell, compared with timeit.py, which uses a single setup
-        statement to import function or create variables. Generally, the bias
-        does not matter as long as results from timeit.py are not mixed with
-        those from %timeit.
-
-**%unalias**::
-
-	Remove an alias
-
-**%upgrade**::
-
-	 Upgrade your IPython installation
-        
-        This will copy the config files that don't yet exist in your 
-        ipython dir from the system config dir. Use this after upgrading 
-        IPython if you don't wish to delete your .ipython dir.
-
-        Call with -nolegacy to get rid of ipythonrc* files (recommended for
-        new users)
-
-**%which**::
-
-	 %which <cmd> => search PATH for files matching cmd. Also scans aliases.
-
-    Traverses PATH and prints all files (not just executables!) that match the
-    pattern on command line. Probably more useful in finding stuff
-    interactively than 'which', which only prints the first matching item.
-    
-    Also discovers and expands aliases, so you'll see what will be executed
-    when you call an alias.
-    
-    Example:
-    
-    [~]|62> %which d
-    d -> ls -F --color=auto
-      == c:\cygwin\bin\ls.exe
-    c:\cygwin\bin\d.exe
-    
-    [~]|64> %which diff*
-    diff3 -> diff3
-      == c:\cygwin\bin\diff3.exe
-    diff -> diff
-      == c:\cygwin\bin\diff.exe
-    c:\cygwin\bin\diff.exe
-    c:\cygwin\bin\diff3.exe
-
-**%who**::
-
-	Print all interactive variables, with some minimal formatting.
-
-        If any arguments are given, only variables whose type matches one of
-        these are printed.  For example:
-
-          %who function str
-
-        will only list functions and strings, excluding all other types of
-        variables.  To find the proper type names, simply use type(var) at a
-        command line to see how python prints type names.  For example:
-
-          In [1]: type('hello')\
-          Out[1]: <type 'str'>
-
-        indicates that the type name for strings is 'str'.
-
-        %who always excludes executed names loaded through your configuration
-        file and things which are internal to IPython.
-
-        This is deliberate, as typically you may load many modules and the
-        purpose of %who is to show you only what you've manually defined.
-
-**%who_ls**::
-
-	Return a sorted list of all interactive variables.
-
-        If arguments are given, only variables of types matching these
-        arguments are returned.
-
-**%whos**::
-
-	Like %who, but gives some extra information about each variable.
-
-        The same type filtering of %who can be applied here.
-
-        For all variables, the type is printed. Additionally it prints:
-        
-          - For {},[],(): their length.
-
-          - For numpy and Numeric arrays, a summary with shape, number of
-          elements, typecode and size in memory.
-
-          - Everything else: a string representation, snipping their middle if
-          too long.
-
-**%xmode**::
-
-	Switch modes for the exception handlers.
-
-        Valid modes: Plain, Context and Verbose.
-
-        If called without arguments, acts as a toggle.
-
-.. magic_end
 
 Access to the standard Python help
 ----------------------------------

docs/sphinxext/inheritance_diagram.py

@@ -39,11 +39,20 b' except ImportError:'
     from md5 import md5
 
 from docutils.nodes import Body, Element
-from docutils.writers.html4css1 import HTMLTranslator
-from sphinx.latexwriter import LaTeXTranslator
 from docutils.parsers.rst import directives
 from sphinx.roles import xfileref_role
 
+def my_import(name):
+    """Module importer - taken from the python documentation.
+
+    This function allows importing names with dots in them."""
+    
+    mod = __import__(name)
+    components = name.split('.')
+    for comp in components[1:]:
+        mod = getattr(mod, comp)
+    return mod
+
 class DotException(Exception):
     pass
 
@@ -84,11 +93,15 b' class InheritanceGraph(object):'
         path = (path and path.rstrip('.'))
         if not path:
             path = base
-        if not path:
-            raise ValueError(
-                "Invalid class or module '%s' specified for inheritance diagram" % name)
         try:
             module = __import__(path, None, None, [])
+            # We must do an import of the fully qualified name.  Otherwise if a
+            # subpackage 'a.b' is requested where 'import a' does NOT provide
+            # 'a.b' automatically, then 'a.b' will not be found below.  This
+            # second call will force the equivalent of 'import a.b' to happen
+            # after the top-level import above.
+            my_import(fullname)
+            
         except ImportError:
             raise ValueError(
                 "Could not import class or module '%s' specified for inheritance diagram" % name)
@@ -277,12 +290,16 b' class inheritance_diagram(Body, Element):'
     """
     pass
 
-def inheritance_diagram_directive_run(class_names, options, state):
+def inheritance_diagram_directive(name, arguments, options, content, lineno,
+                                  content_offset, block_text, state,
+                                  state_machine):
     """
     Run when the inheritance_diagram directive is first encountered.
     """
     node = inheritance_diagram()
 
+    class_names = arguments
+
     # Create a graph starting with the list of classes
     graph = InheritanceGraph(class_names)
 
@@ -315,15 +332,12 b' def html_output_graph(self, node):'
 
     graph_hash = get_graph_hash(node)
     name = "inheritance%s" % graph_hash
-    png_path = os.path.join('_static', name + ".png")
-
-    path = '_static'
-    source = self.document.attributes['source']
-    count = source.split('/doc/')[-1].count('/')
-    for i in range(count):
-        if os.path.exists(path): break
-        path = '../'+path
-    path = '../'+path #specifically added for matplotlib
+    path = '_images'
+    dest_path = os.path.join(setup.app.builder.outdir, path)
+    if not os.path.exists(dest_path):
+        os.makedirs(dest_path)
+    png_path = os.path.join(dest_path, name + ".png")
+    path = setup.app.builder.imgpath
 
     # Create a mapping from fully-qualified class names to URLs.
     urls = {}
@@ -349,11 +363,14 b' def latex_output_graph(self, node):'
 
     graph_hash = get_graph_hash(node)
     name = "inheritance%s" % graph_hash
-    pdf_path = os.path.join('_static', name + ".pdf")
+    dest_path = os.path.abspath(os.path.join(setup.app.builder.outdir, '_images'))
+    if not os.path.exists(dest_path):
+        os.makedirs(dest_path)
+    pdf_path = os.path.abspath(os.path.join(dest_path, name + ".pdf"))
 
     graph.run_dot(['-Tpdf', '-o%s' % pdf_path],
                   name, parts, graph_options={'size': '"6.0,6.0"'})
-    return '\\includegraphics{../../%s}' % pdf_path
+    return '\n\\includegraphics{%s}\n\n' % pdf_path
 
 def visit_inheritance_diagram(inner_func):
     """
@@ -377,47 +394,14 b' def visit_inheritance_diagram(inner_func):'
 def do_nothing(self, node):
     pass
 
-options_spec = {
-    'parts': directives.nonnegative_int
-    }
-
-# Deal with the old and new way of registering directives
-try:
-    from docutils.parsers.rst import Directive
-except ImportError:
-    from docutils.parsers.rst.directives import _directives
-    def inheritance_diagram_directive(name, arguments, options, content, lineno,
-                                      content_offset, block_text, state,
-                                      state_machine):
-        return inheritance_diagram_directive_run(arguments, options, state)
-    inheritance_diagram_directive.__doc__ = __doc__
-    inheritance_diagram_directive.arguments = (1, 100, 0)
-    inheritance_diagram_directive.options = options_spec
-    inheritance_diagram_directive.content = 0
-    _directives['inheritance-diagram'] = inheritance_diagram_directive
-else:
-    class inheritance_diagram_directive(Directive):
-        has_content = False
-        required_arguments = 1
-        optional_arguments = 100
-        final_argument_whitespace = False
-        option_spec = options_spec
-
-        def run(self):
-            return inheritance_diagram_directive_run(
-                self.arguments, self.options, self.state)
-    inheritance_diagram_directive.__doc__ = __doc__
-
-    directives.register_directive('inheritance-diagram',
-                                  inheritance_diagram_directive)
-
 def setup(app):
-    app.add_node(inheritance_diagram)
-
-    HTMLTranslator.visit_inheritance_diagram = \
-        visit_inheritance_diagram(html_output_graph)
-    HTMLTranslator.depart_inheritance_diagram = do_nothing
-
-    LaTeXTranslator.visit_inheritance_diagram = \
-        visit_inheritance_diagram(latex_output_graph)
-    LaTeXTranslator.depart_inheritance_diagram = do_nothing
+    setup.app = app
+    setup.confdir = app.confdir
+
+    app.add_node(
+        inheritance_diagram,
+        latex=(visit_inheritance_diagram(latex_output_graph), do_nothing),
+        html=(visit_inheritance_diagram(html_output_graph), do_nothing))
+    app.add_directive(
+        'inheritance-diagram', inheritance_diagram_directive,
+        False, (1, 100, 0), parts = directives.nonnegative_int)

docs/sphinxext/ipython_console_highlighting.py

@@ -1,18 +1,32 b''
+"""reST directive for syntax-highlighting ipython interactive sessions.
+"""
+
+#-----------------------------------------------------------------------------
+# Needed modules
+
+# Standard library
+import re
+
+# Third party
 from pygments.lexer import Lexer, do_insertions
-from pygments.lexers.agile import PythonConsoleLexer, PythonLexer, \
-    PythonTracebackLexer
+from pygments.lexers.agile import (PythonConsoleLexer, PythonLexer, 
+                                   PythonTracebackLexer)
 from pygments.token import Comment, Generic
+
 from sphinx import highlighting
-import re
 
+
+#-----------------------------------------------------------------------------
+# Global constants
 line_re = re.compile('.*?\n')
 
+#-----------------------------------------------------------------------------
+# Code begins - classes and functions
+
 class IPythonConsoleLexer(Lexer):
     """
     For IPython console output or doctests, such as:
 
-    Tracebacks are not currently supported.
-
     .. sourcecode:: ipython
 
       In [1]: a = 'foo'
@@ -24,7 +38,14 b' class IPythonConsoleLexer(Lexer):'
       foo
 
       In [4]: 1 / 0
+
+    Notes:
+
+      - Tracebacks are not currently supported.
+
+      - It assumes the default IPython prompts, not customized ones.
     """
+    
     name = 'IPython console session'
     aliases = ['ipython']
     mimetypes = ['text/x-ipython-console']
@@ -72,4 +93,6 b' class IPythonConsoleLexer(Lexer):'
                                       pylexer.get_tokens_unprocessed(curcode)):
                 yield item
 
+#-----------------------------------------------------------------------------
+# Register the extension as a valid pygments lexer
 highlighting.lexers['ipython'] = IPythonConsoleLexer()