Merge pull request #4540 from takluyver/apidocs3

Apidocs3

IPython/core/inputsplitter.py

@@ -212,7 +212,7 b' def get_input_encoding():'
 #-----------------------------------------------------------------------------
 
 class InputSplitter(object):
-    """An object that can accumulate lines of Python source before execution.
+    r"""An object that can accumulate lines of Python source before execution.
 
     This object is designed to be fed python source line-by-line, using
        :meth:`push`. It will return on each push whether the currently pushed

IPython/core/interactiveshell.py

@@ -131,9 +131,9 b' def get_default_colors():'
 
 
 class SeparateUnicode(Unicode):
-    """A Unicode subclass to validate separate_in, separate_out, etc.
+    r"""A Unicode subclass to validate separate_in, separate_out, etc.
 
-    This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
+    This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
     """
 
     def validate(self, obj, value):
@@ -3035,15 +3035,17 b' class InteractiveShell(SingletonConfigurable):'
             arguments as strings. The number before the / is the session
             number: ~n goes n back from the current session.
 
-        Optional Parameters:
-          - raw(False): by default, the processed input is used.  If this is
-            true, the raw input history is used instead.
+        raw : bool, optional
+            By default, the processed input is used.  If this is true, the raw
+            input history is used instead.
 
-        Note that slices can be called with two notations:
+        Notes
+        -----
 
-        N:M -> standard python form, means including items N...(M-1).
+        Slices can be described with two notations:
 
-        N-M -> include items N..M (closed endpoint).
+        * ``N:M`` -> standard python form, means including items N...(M-1).
+        * ``N-M`` -> include items N..M (closed endpoint).
         """
         lines = self.history_manager.get_range_by_str(range_str, raw=raw)
         return "\n".join(x for _, _, x in lines)

IPython/core/magic.py

@@ -579,24 +579,36 b' class Magics(Configurable):'
     def parse_options(self, arg_str, opt_str, *long_opts, **kw):
         """Parse options passed to an argument string.
 
-        The interface is similar to that of getopt(), but it returns back a
-        Struct with the options as keys and the stripped argument string still
-        as a string.
+        The interface is similar to that of :func:`getopt.getopt`, but it
+        returns a :class:`~IPython.utils.struct.Struct` with the options as keys
+        and the stripped argument string still as a string.
 
         arg_str is quoted as a true sys.argv vector by using shlex.split.
         This allows us to easily expand variables, glob files, quote
         arguments, etc.
 
-        Options:
-          -mode: default 'string'. If given as 'list', the argument string is
-          returned as a list (split on whitespace) instead of a string.
+        Parameters
+        ----------
+
+        arg_str : str
+          The arguments to parse.
 
-          -list_all: put all option values in lists. Normally only options
+        opt_str : str
+          The options specification.
+
+        mode : str, default 'string'
+          If given as 'list', the argument string is returned as a list (split
+          on whitespace) instead of a string.
+
+        list_all : bool, default False
+          Put all option values in lists. Normally only options
           appearing more than once are put in a list.
 
-          -posix (True): whether to split the input line in POSIX mode or not,
-          as per the conventions outlined in the shlex module from the
-          standard library."""
+        posix : bool, default True
+          Whether to split the input line in POSIX mode or not, as per the
+          conventions outlined in the :mod:`shlex` module from the standard
+          library.
+        """
 
         # inject default options at the beginning of the input line
         caller = sys._getframe(1).f_code.co_name

IPython/core/magic_arguments.py

@@ -51,18 +51,57 b' Inheritance diagram:'
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 import argparse
+import re
 
 # Our own imports
 from IPython.core.error import UsageError
+from IPython.utils.decorators import undoc
 from IPython.utils.process import arg_split
 from IPython.utils.text import dedent
 
+NAME_RE = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]*$")
+
+@undoc
 class MagicHelpFormatter(argparse.RawDescriptionHelpFormatter):
-    """ A HelpFormatter which dedents but otherwise preserves indentation.
+    """A HelpFormatter with a couple of changes to meet our needs.
     """
+    # Modified to dedent text.
     def _fill_text(self, text, width, indent):
         return argparse.RawDescriptionHelpFormatter._fill_text(self, dedent(text), width, indent)
 
+    # Modified to wrap argument placeholders in <> where necessary.
+    def _format_action_invocation(self, action):
+        if not action.option_strings:
+            metavar, = self._metavar_formatter(action, action.dest)(1)
+            return metavar
+
+        else:
+            parts = []
+
+            # if the Optional doesn't take a value, format is:
+            #    -s, --long
+            if action.nargs == 0:
+                parts.extend(action.option_strings)
+
+            # if the Optional takes a value, format is:
+            #    -s ARGS, --long ARGS
+            else:
+                default = action.dest.upper()
+                args_string = self._format_args(action, default)
+                # IPYTHON MODIFICATION: If args_string is not a plain name, wrap
+                # it in <> so it's valid RST.
+                if not NAME_RE.match(args_string):
+                    args_string = "<%s>" % args_string
+                for option_string in action.option_strings:
+                    parts.append('%s %s' % (option_string, args_string))
+
+            return ', '.join(parts)
+
+    # Override the default prefix ('usage') to our % magic escape,
+    # in a code block.
+    def add_usage(self, usage, actions, groups, prefix="::\n\n  %"):
+        super(MagicHelpFormatter, self).add_usage(usage, actions, groups, prefix)
+
 class MagicArgumentParser(argparse.ArgumentParser):
     """ An ArgumentParser tweaked for use by IPython magics.
     """
@@ -113,15 +152,8 b' def construct_parser(magic_func):'
         if result is not None:
             group = result
 
-    # Replace the starting 'usage: ' with IPython's %.
-    help_text = parser.format_help()
-    if help_text.startswith('usage: '):
-        help_text = help_text.replace('usage: ', '%', 1)
-    else:
-        help_text = '%' + help_text
-
     # Replace the magic function's docstring with the full help text.
-    magic_func.__doc__ = help_text
+    magic_func.__doc__ = parser.format_help()
 
     return parser
 

IPython/core/magics/basic.py

@@ -114,6 +114,7 b' class BasicMagics(Magics):'
         Examples
         --------
         ::
+
           In [1]: %alias_magic t timeit
           Created `%t` as an alias for `%timeit`.
           Created `%%t` as an alias for `%%timeit`.

IPython/core/magics/code.py

@@ -275,7 +275,7 b' class CodeMagics(Magics):'
           where source can be a filename, URL, input history range or macro
 
         Options:
-        --------
+
           -r <lines>: Specify lines or ranges of lines to load from the source.
           Ranges could be specified as x-y (x..y) or in python-style x:y 
           (x..(y-1)). Both limits x and y can be left blank (meaning the 

IPython/core/tests/test_magic_arguments.py

@@ -74,44 +74,44 b' def foo(self, args):'
 
 
 def test_magic_arguments():
-    assert_equal(magic_foo1.__doc__, '%foo1 [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
+    assert_equal(magic_foo1.__doc__, '::\n\n  %foo1 [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
     assert_equal(getattr(magic_foo1, 'argcmd_name', None), None)
     assert_equal(real_name(magic_foo1), 'foo1')
     assert_equal(magic_foo1(None, ''), argparse.Namespace(foo=None))
     assert hasattr(magic_foo1, 'has_arguments')
 
-    assert_equal(magic_foo2.__doc__, '%foo2\n\n A docstring.\n')
+    assert_equal(magic_foo2.__doc__, '::\n\n  %foo2\n\n A docstring.\n')
     assert_equal(getattr(magic_foo2, 'argcmd_name', None), None)
     assert_equal(real_name(magic_foo2), 'foo2')
     assert_equal(magic_foo2(None, ''), argparse.Namespace())
     assert hasattr(magic_foo2, 'has_arguments')
 
-    assert_equal(magic_foo3.__doc__, '%foo3 [-f FOO] [-b BAR] [-z BAZ]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n\nGroup:\n  -b BAR, --bar BAR  a grouped argument\n\nSecond Group:\n  -z BAZ, --baz BAZ  another grouped argument\n')
+    assert_equal(magic_foo3.__doc__, '::\n\n  %foo3 [-f FOO] [-b BAR] [-z BAZ]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n\nGroup:\n  -b BAR, --bar BAR  a grouped argument\n\nSecond Group:\n  -z BAZ, --baz BAZ  another grouped argument\n')
     assert_equal(getattr(magic_foo3, 'argcmd_name', None), None)
     assert_equal(real_name(magic_foo3), 'foo3')
     assert_equal(magic_foo3(None, ''),
                        argparse.Namespace(bar=None, baz=None, foo=None))
     assert hasattr(magic_foo3, 'has_arguments')
 
-    assert_equal(magic_foo4.__doc__, '%foo4 [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
+    assert_equal(magic_foo4.__doc__, '::\n\n  %foo4 [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
     assert_equal(getattr(magic_foo4, 'argcmd_name', None), None)
     assert_equal(real_name(magic_foo4), 'foo4')
     assert_equal(magic_foo4(None, ''), argparse.Namespace())
     assert hasattr(magic_foo4, 'has_arguments')
 
-    assert_equal(magic_foo5.__doc__, '%frobnicate [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
+    assert_equal(magic_foo5.__doc__, '::\n\n  %frobnicate [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
     assert_equal(getattr(magic_foo5, 'argcmd_name', None), 'frobnicate')
     assert_equal(real_name(magic_foo5), 'frobnicate')
     assert_equal(magic_foo5(None, ''), argparse.Namespace(foo=None))
     assert hasattr(magic_foo5, 'has_arguments')
 
-    assert_equal(magic_magic_foo.__doc__, '%magic_foo [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
+    assert_equal(magic_magic_foo.__doc__, '::\n\n  %magic_foo [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
     assert_equal(getattr(magic_magic_foo, 'argcmd_name', None), None)
     assert_equal(real_name(magic_magic_foo), 'magic_foo')
     assert_equal(magic_magic_foo(None, ''), argparse.Namespace(foo=None))
     assert hasattr(magic_magic_foo, 'has_arguments')
 
-    assert_equal(foo.__doc__, '%foo [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
+    assert_equal(foo.__doc__, '::\n\n  %foo [-f FOO]\n\n A docstring.\n\noptional arguments:\n  -f FOO, --foo FOO  an argument\n')
     assert_equal(getattr(foo, 'argcmd_name', None), None)
     assert_equal(real_name(foo), 'foo')
     assert_equal(foo(None, ''), argparse.Namespace(foo=None))

IPython/core/ultratb.py

@@ -2,7 +2,8 b''
 """
 ultratb.py -- Spice up your tracebacks!
 
-* ColorTB
+**ColorTB**
+
 I've always found it a bit hard to visually parse tracebacks in Python.  The
 ColorTB class is a solution to that problem.  It colors the different parts of a
 traceback in a manner similar to what you would expect from a syntax-highlighting
@@ -13,7 +14,8 b' Installation instructions for ColorTB::'
     import sys,ultratb
     sys.excepthook = ultratb.ColorTB()
 
-* VerboseTB
+**VerboseTB**
+
 I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds
 of useful info when a traceback occurs.  Ping originally had it spit out HTML
 and intended it for CGI programmers, but why should they have all the fun?  I

IPython/extensions/cythonmagic.py

@@ -68,6 +68,7 b' from IPython.core import magic_arguments'
 from IPython.core.magic import Magics, magics_class, cell_magic
 from IPython.utils import py3compat
 from IPython.utils.path import get_ipython_cache_dir
+from IPython.utils.text import dedent
 
 import Cython
 from Cython.Compiler.Errors import CompileError
@@ -331,9 +332,12 b' class CythonMagics(Magics):'
         return html
 
 __doc__ = __doc__.format(
-                CYTHON_DOC = ' '*8 + CythonMagics.cython.__doc__,
-                CYTHON_INLINE_DOC = ' '*8 + CythonMagics.cython_inline.__doc__,
-                CYTHON_PYXIMPORT_DOC = ' '*8 + CythonMagics.cython_pyximport.__doc__,
+                # rST doesn't see the -+ flag as part of an option list, so we
+                # hide it from the module-level docstring.
+                CYTHON_DOC = dedent(CythonMagics.cython.__doc__\
+                            .replace('-+, --cplus','--cplus    ')),
+                CYTHON_INLINE_DOC = dedent(CythonMagics.cython_inline.__doc__),
+                CYTHON_PYXIMPORT_DOC = dedent(CythonMagics.cython_pyximport.__doc__),
 )
 
 def load_ipython_extension(ip):

IPython/extensions/octavemagic.py

@@ -55,6 +55,7 b' from IPython.core.magic_arguments import ('
     argument, magic_arguments, parse_argstring
 )
 from IPython.utils.py3compat import unicode_to_str
+from IPython.utils.text import dedent
 
 class OctaveMagicError(oct2py.Oct2PyError):
     pass
@@ -145,6 +146,8 b' class OctaveMagics(Magics):'
         '''
         Line-level magic that pulls a variable from Octave.
 
+        ::
+
             In [18]: _ = %octave x = [1 2; 3 4]; y = 'hello'
 
             In [19]: %octave_pull x y
@@ -195,7 +198,7 b' class OctaveMagics(Magics):'
     def octave(self, line, cell=None, local_ns=None):
         '''
         Execute code in Octave, and pull some of the results back into the
-        Python namespace.
+        Python namespace::
 
             In [9]: %octave X = [1 2; 3 4]; mean(X)
             Out[9]: array([[ 2., 3.]])
@@ -209,7 +212,7 b' class OctaveMagics(Magics):'
 
             -2*x^4 - 1*x^3 + 0*x^2 + 1*x^1 + 2
 
-        In the notebook, plots are published as the output of the cell, e.g.
+        In the notebook, plots are published as the output of the cell, e.g.::
 
         %octave plot([1 2 3], [4 5 6])
 
@@ -360,9 +363,9 b' class OctaveMagics(Magics):'
 
 
 __doc__ = __doc__.format(
-    OCTAVE_DOC = ' '*8 + OctaveMagics.octave.__doc__,
-    OCTAVE_PUSH_DOC = ' '*8 + OctaveMagics.octave_push.__doc__,
-    OCTAVE_PULL_DOC = ' '*8 + OctaveMagics.octave_pull.__doc__
+    OCTAVE_DOC = dedent(OctaveMagics.octave.__doc__),
+    OCTAVE_PUSH_DOC = dedent(OctaveMagics.octave_push.__doc__),
+    OCTAVE_PULL_DOC = dedent(OctaveMagics.octave_pull.__doc__)
     )
 
 

IPython/extensions/rmagic.py

@@ -75,6 +75,7 b' from IPython.core.magic_arguments import ('
 from IPython.external.simplegeneric import generic
 from IPython.utils.py3compat import (str_to_unicode, unicode_to_str, PY3,
                                      unicode_type)
+from IPython.utils.text import dedent
 
 class RInterpreterError(ri.RRuntimeError):
     """An error when running R code in a %%R magic cell."""
@@ -679,10 +680,10 b' class RMagics(Magics):'
                 return self.Rconverter(result, dataframe=False)
 
 __doc__ = __doc__.format(
-                R_DOC = ' '*8 + RMagics.R.__doc__,
-                RPUSH_DOC = ' '*8 + RMagics.Rpush.__doc__,
-                RPULL_DOC = ' '*8 + RMagics.Rpull.__doc__,
-                RGET_DOC = ' '*8 + RMagics.Rget.__doc__
+                R_DOC = dedent(RMagics.R.__doc__),
+                RPUSH_DOC = dedent(RMagics.Rpush.__doc__),
+                RPULL_DOC = dedent(RMagics.Rpull.__doc__),
+                RGET_DOC = dedent(RMagics.Rget.__doc__)
 )
 
 

IPython/html/services/notebooks/handlers.py

@@ -145,9 +145,11 b' class NotebookHandler(IPythonHandler):'
         
         POST creates new notebooks. The server always decides on the notebook name.
         
-        POST /api/notebooks/path : new untitled notebook in path
-            If content specified, upload a notebook, otherwise start empty.
-        POST /api/notebooks/path?copy=OtherNotebook.ipynb : new copy of OtherNotebook in path
+        POST /api/notebooks/path
+          New untitled notebook in path. If content specified, upload a
+          notebook, otherwise start empty.
+        POST /api/notebooks/path?copy=OtherNotebook.ipynb
+          New copy of OtherNotebook in path
         """
         
         if name is not None:
@@ -171,14 +173,15 b' class NotebookHandler(IPythonHandler):'
     def put(self, path='', name=None):
         """Saves the notebook in the location specified by name and path.
         
-        PUT /api/notebooks/path/Name.ipynb : Save notebook at path/Name.ipynb
-            Notebook structure is specified in `content` key of JSON request body.
-            If content is not specified, create a new empty notebook.
-        PUT /api/notebooks/path/Name.ipynb?copy=OtherNotebook.ipynb : copy OtherNotebook to Name
+        PUT is very similar to POST, but the requester specifies the name,
+        whereas with POST, the server picks the name.
         
-        POST and PUT are basically the same. The only difference:
-        
-        - with POST, server always picks the name, with PUT the requester does
+        PUT /api/notebooks/path/Name.ipynb
+          Save notebook at ``path/Name.ipynb``. Notebook structure is specified
+          in `content` key of JSON request body. If content is not specified,
+          create a new empty notebook.
+        PUT /api/notebooks/path/Name.ipynb?copy=OtherNotebook.ipynb
+          Copy OtherNotebook to Name
         """
         if name is None:
             raise web.HTTPError(400, "Only PUT to full names. Use POST for directories.")

IPython/kernel/channels.py

@@ -133,9 +133,9 b' class ZMQSocketChannel(Thread):'
     def stop(self):
         """Stop the channel's event loop and join its thread.
 
-        This calls :method:`Thread.join` and returns when the thread
+        This calls :meth:`~threading.Thread.join` and returns when the thread
         terminates. :class:`RuntimeError` will be raised if
-        :method:`self.start` is called again.
+        :meth:`~threading.Thread.start` is called again.
         """
         self.join()
 
@@ -430,7 +430,7 b' class IOPubChannel(ZMQSocketChannel):'
     def flush(self, timeout=1.0):
         """Immediately processes all pending messages on the iopub channel.
 
-        Callers should use this method to ensure that :method:`call_handlers`
+        Callers should use this method to ensure that :meth:`call_handlers`
         has been called for all messages that have been received on the
         0MQ SUB socket of this channel.
 

IPython/kernel/client.py

@@ -102,7 +102,7 b' class KernelClient(LoggingConfigurable, ConnectionFileMixin):'
         This will create the channels if they do not exist and then start
         them (their activity runs in a thread). If port numbers of 0 are
         being used (random ports) then you must first call
-        :method:`start_kernel`. If the channels have been stopped and you
+        :meth:`start_kernel`. If the channels have been stopped and you
         call this, :class:`RuntimeError` will be raised.
         """
         if shell:

IPython/kernel/manager.py

@@ -185,8 +185,8 b' class KernelManager(LoggingConfigurable, ConnectionFileMixin):'
         If random ports (port=0) are being used, this method must be called
         before the channels are created.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         **kw : optional
              keyword arguments that are passed down to build the kernel_cmd
              and launching the kernel (e.g. Popen kwargs).
@@ -227,8 +227,8 b' class KernelManager(LoggingConfigurable, ConnectionFileMixin):'
         2. If that fails, the kernel is shutdown forcibly by sending it
            a signal.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         now : bool
             Should the kernel be forcible killed *now*. This skips the
             first, nice shutdown attempt.

IPython/kernel/zmq/parentpoller.py

@@ -48,8 +48,8 b' class ParentPollerWindows(Thread):'
         """ Create the poller. At least one of the optional parameters must be
         provided.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         interrupt_handle : HANDLE (int), optional
             If provided, the program will generate a Ctrl+C event when this
             handle is signaled.

IPython/kernel/zmq/session.py

@@ -527,11 +527,13 b' class Session(Configurable):'
         Returns
         -------
         msg_list : list
-            The list of bytes objects to be sent with the format:
-            [ident1,ident2,...,DELIM,HMAC,p_header,p_parent,p_metadata,p_content,
-             buffer1,buffer2,...]. In this list, the p_* entities are
-            the packed or serialized versions, so if JSON is used, these
-            are utf8 encoded JSON strings.
+            The list of bytes objects to be sent with the format::
+
+                [ident1, ident2, ..., DELIM, HMAC, p_header, p_parent,
+                 p_metadata, p_content, buffer1, buffer2, ...]
+
+            In this list, the ``p_*`` entities are the packed or serialized
+            versions, so if JSON is used, these are utf8 encoded JSON strings.
         """
         content = msg.get('content', {})
         if content is None:
@@ -781,8 +783,8 b' class Session(Configurable):'
         methods work with full message lists, whereas pack/unpack work with
         the individual message parts in the message list.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         msg_list : list of bytes or Message objects
             The list of message parts of the form [HMAC,p_header,p_parent,
             p_metadata,p_content,buffer1,buffer2,...].

IPython/kernel/zmq/zmqshell.py

@@ -197,31 +197,26 b' class KernelMagics(Magics):'
         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.
+        -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.
+        -p
+          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
+        -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:
@@ -237,7 +232,7 b' class KernelMagics(Magics):'
 
         - 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`
+          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.
 
@@ -255,58 +250,11 b' class KernelMagics(Magics):'
         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.
+        Unlike in the terminal, this is designed to use a GUI editor, and we do
+        not know when it has closed. So the file you edit will not be
+        automatically executed or printed.
 
         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 [5]: ed
-        Editing... done. Executing edited code...
-        hello
-        Out[5]: "print 'hello'n"
-
-        Now we call it again with the previous output (stored in _):
-
-        In [6]: ed _
-        Editing... done. Executing edited code...
-        hello world
-        Out[6]: "print 'hello world'n"
-
-        Now we call it with the output #8 (stored in _8, also as Out[8]):
-
-        In [7]: ed _8
-        Editing... done. Executing edited code...
-        hello again
-        Out[7]: "print 'hello again'n"
         """
 
         opts,args = self.parse_options(parameter_s,'prn:')

IPython/lib/backgroundjobs.py

@@ -366,7 +366,8 b' class BackgroundJobBase(threading.Thread):'
     - A strform attribute used in calls to __str__.
 
     - A call() method, which will make the actual execution call and must
-    return a value to be held in the 'result' field of the job object."""
+      return a value to be held in the 'result' field of the job object.
+    """
 
     # Class constants for status, in string and as numerical codes (when
     # updating jobs lists, we don't want to do string comparisons).  This will
@@ -378,6 +379,10 b' class BackgroundJobBase(threading.Thread):'
     stat_dead_c = -1
 
     def __init__(self):
+        """Must be implemented in subclasses.
+
+        Subclasses must call :meth:`_init` for standard initialisation.
+        """
         raise NotImplementedError("This class can not be instantiated directly.")
 
     def _init(self):

IPython/lib/display.py

@@ -49,6 +49,7 b' class Audio(DisplayObject):'
 
     Examples
     --------
+    ::
   
     # Generate a sound
     import numpy as np
@@ -57,13 +58,13 b' class Audio(DisplayObject):'
     data = np.sin(2*np.pi*220*t) + np.sin(2*np.pi*224*t))
     Audio(data,rate=framerate)
 
-    Audio("http://www.nch.com.au/acm/8k16bitpcm.wav")
+        Audio("http://www.nch.com.au/acm/8k16bitpcm.wav")  # From URL
     Audio(url="http://www.w3schools.com/html/horse.ogg")
     
-    Audio('/path/to/sound.wav')
+        Audio('/path/to/sound.wav')  # From file
     Audio(filename='/path/to/sound.ogg')
     
-    Audio(b'RAW_WAV_DATA..)
+        Audio(b'RAW_WAV_DATA..)  # From bytes
     Audio(data=b'RAW_WAV_DATA..)
 
     """
@@ -198,21 +199,20 b' class IFrame(object):'
 class YouTubeVideo(IFrame):
     """Class for embedding a YouTube Video in an IPython session, based on its video id.
 
-    e.g. to embed the video on this page:
-
-    http://www.youtube.com/watch?v=foo
-
-    you would do:
+    e.g. to embed the video from http://www.youtube.com/watch?v=foo , you would
+    do::
 
     vid = YouTubeVideo("foo")
     display(vid)
 
-    To start from 30 seconds:
+    To start from 30 seconds::
 
     vid = YouTubeVideo("abc", start=30)
     display(vid)
 
-    To calculate seconds from time as hours, minutes, seconds use:
+    To calculate seconds from time as hours, minutes, seconds use
+    :class:`datetime.timedelta`::
+
     start=int(timedelta(hours=1, minutes=46, seconds=40).total_seconds())
 
     Other parameters can be provided as documented at
@@ -316,17 +316,15 b' class FileLink(object):'
 class FileLinks(FileLink):
     """Class for embedding local file links in an IPython session, based on path
 
-    e.g. to embed links to files that were generated in the IPython notebook under my/data
-
-    you would do:
+    e.g. to embed links to files that were generated in the IPython notebook
+    under ``my/data``, you would do::
 
     local_files = FileLinks("my/data")
     display(local_files)
 
-    or in the HTML notebook, just
+    or in the HTML notebook, just::
 
     FileLinks("my/data")
-
     """
     def __init__(self,
                  path,
@@ -337,35 +335,38 b' class FileLinks(FileLink):'
                  notebook_display_formatter=None,
                  terminal_display_formatter=None):
         """
-            included_suffixes : list of filename suffixes to include when
-             formatting output [default: include all files]
+        See :class:`FileLink` for the ``path``, ``url_prefix``,
+        ``result_html_prefix`` and ``result_html_suffix`` parameters.
 
-            See the FileLink (baseclass of LocalDirectory) docstring for
-             information on additional parameters.
+        included_suffixes : list
+          Filename suffixes to include when formatting output [default: include
+          all files]
 
-            notebook_display_formatter : func used to format links for display
-             in the notebook. See discussion of formatter function below.
+        notebook_display_formatter : function
+          Used to format links for display in the notebook. See discussion of
+          formatter functions below.
 
-            terminal_display_formatter : func used to format links for display
-             in the terminal. See discussion of formatter function below.
+        terminal_display_formatter : function
+          Used to format links for display in the terminal. See discussion of
+          formatter functions below.
 
+        Formatter functions must be of the form::
 
-            Passing custom formatter functions
-            ----------------------------------
-             Formatter functions must be of the form:
               f(dirname, fnames, included_suffixes)
-               dirname : the name of a directory (a string),
-               fnames :  a list of the files in that directory
-               included_suffixes : a list of the file suffixes that should be
-                                   included in the output (passing None means
-                                   to include all suffixes in the output in
-                                   the built-in formatters)
-
-               returns a list of lines that should will be print in the
-               notebook (if passing notebook_display_formatter) or the terminal
-               (if passing terminal_display_formatter). This function is iterated
-               over for each directory in self.path. Default formatters are in
-               place, can be passed here to support alternative formatting.
+
+        dirname : str
+          The name of a directory
+        fnames : list
+          The files in that directory
+        included_suffixes : list
+          The file suffixes that should be included in the output (passing None
+          meansto include all suffixes in the output in the built-in formatters)
+
+        The function should return a list of lines that will be printed in the
+        notebook (if passing notebook_display_formatter) or the terminal (if
+        passing terminal_display_formatter). This function is iterated over for
+        each directory in self.path. Default formatters are in place, can be
+        passed here to support alternative formatting.
 
         """
         if isfile(path):

IPython/lib/security.py

@@ -49,8 +49,8 b" def passwd(passphrase=None, algorithm='sha1'):"
 
     Examples
     --------
-    In [1]: passwd('mypassword')
-    Out[1]: 'sha1:7cf3:b7d6da294ea9592a9480c8f52e63cd42cfb9dd12'
+    >>> passwd('mypassword')
+    'sha1:7cf3:b7d6da294ea9592a9480c8f52e63cd42cfb9dd12'
 
     """
     if passphrase is None:
@@ -89,16 +89,14 b' def passwd_check(hashed_passphrase, passphrase):'
 
     Examples
     --------
-    In [1]: from IPython.lib.security import passwd_check
-
-    In [2]: passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
-       ...:              'mypassword')
-    Out[2]: True
-
-    In [3]: passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
-       ...:              'anotherpassword')
-    Out[3]: False
-
+    >>> from IPython.lib.security import passwd_check
+    >>> passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
+    ...              'mypassword')
+    True
+
+    >>> passwd_check('sha1:0e112c3ddfce:a68df677475c2b47b6e86d0467eec97ac5f4b85a',
+    ...              'anotherpassword')
+    False
     """
     try:
         algorithm, salt, pw_digest = hashed_passphrase.split(':', 2)

IPython/nbconvert/exporters/export.py

@@ -16,7 +16,7 b' Module containing single call export functions.'
 from functools import wraps
 
 from IPython.nbformat.v3.nbbase import NotebookNode
-from IPython.config import Config
+from IPython.utils.decorators import undoc
 from IPython.utils.py3compat import string_types
 
 from .exporter import Exporter
@@ -32,18 +32,20 b' from .rst import RSTExporter'
 # Classes
 #-----------------------------------------------------------------------------
 
+@undoc
 def DocDecorator(f):
     
     #Set docstring of function
     f.__doc__ = f.__doc__ + """
-    nb : Notebook node
+    nb : :class:`~{nbnode_mod}.NotebookNode`
+      The notebook to export.
     config : config (optional, keyword arg)
         User configuration instance.
     resources : dict (optional, keyword arg)
         Resources used in the conversion process.
         
     Returns
-    ----------
+    -------
     tuple- output, resources, exporter_instance
     output : str
         Jinja 2 output.  This is the resulting converted notebook.
@@ -55,8 +57,10 b' def DocDecorator(f):'
         to caller because it provides a 'file_extension' property which
         specifies what extension the output should be saved as.
 
+    Notes
+    -----
     WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
-    """
+    """.format(nbnode_mod=NotebookNode.__module__)
             
     @wraps(f)
     def decorator(*args, **kwargs):
@@ -92,10 +96,12 b' def export(exporter, nb, **kw):'
     """
     Export a notebook object using specific exporter class.
     
-    exporter : Exporter class type or instance
+    Parameters
+    ----------
+    exporter : class:`~IPython.nbconvert.exporters.exporter.Exporter` class or instance
         Class type or instance of the exporter that should be used.  If the 
         method initializes it's own instance of the class, it is ASSUMED that 
-        the class type provided exposes a constructor (__init__) with the same 
+      the class type provided exposes a constructor (``__init__``) with the same
         signature as the base Exporter class.
     """
     
@@ -152,6 +158,8 b' def export_by_name(format_name, nb, **kw):'
     (Inspect) is used to find the template's corresponding explicit export
     method defined in this module.  That method is then called directly.
     
+    Parameters
+    ----------
     format_name : str
         Name of the template style to export to.
     """

IPython/nbconvert/exporters/exporter.py

@@ -32,9 +32,6 b' from IPython.utils.traitlets import MetaHasTraits, Unicode, List'
 from IPython.utils.importstring import import_item
 from IPython.utils import text, py3compat
 
-from IPython.nbconvert import preprocessors as nbpreprocessors
-
-
 #-----------------------------------------------------------------------------
 # Class
 #-----------------------------------------------------------------------------
@@ -96,17 +93,20 b' class Exporter(LoggingConfigurable):'
     def default_config(self):
         return Config()
 
-
+    @nbformat.docstring_nbformat_mod
     def from_notebook_node(self, nb, resources=None, **kw):
         """
         Convert a notebook from a notebook node instance.
 
         Parameters
         ----------
-        nb : Notebook node
-        resources : dict (**kw)
-            of additional resources that can be accessed read/write by
-            preprocessors.
+        nb : :class:`~{nbformat_mod}.nbbase.NotebookNode`
+          Notebook node
+        resources : dict
+          Additional resources that can be accessed read/write by
+          preprocessors and filters.
+        **kw
+          Ignored (?)
         """
         nb_copy = copy.deepcopy(nb)
         resources = self._init_resources(resources)

IPython/nbconvert/exporters/templateexporter.py

@@ -27,6 +27,7 b' from IPython.utils.traitlets import MetaHasTraits, Unicode, List, Dict, Any'
 from IPython.utils.importstring import import_item
 from IPython.utils import py3compat, text
 
+from IPython.nbformat.current import docstring_nbformat_mod
 from IPython.nbconvert import filters
 from .exporter import Exporter
 
@@ -187,15 +188,17 b' class TemplateExporter(Exporter):'
                 self.log.info("Loaded template %s", try_name)
                 break
     
+    @docstring_nbformat_mod
     def from_notebook_node(self, nb, resources=None, **kw):
         """
         Convert a notebook from a notebook node instance.
     
         Parameters
         ----------
-        nb : Notebook node
-        resources : dict (**kw) 
-            of additional resources that can be accessed read/write by 
+        nb : :class:`~{nbformat_mod}.nbbase.NotebookNode`
+          Notebook node
+        resources : dict
+          Additional resources that can be accessed read/write by
             preprocessors and filters.
         """
         nb_copy, resources = super(TemplateExporter, self).from_notebook_node(nb, resources, **kw)

IPython/nbconvert/nbconvertapp.py

@@ -77,7 +77,7 b' nbconvert_flags.update({'
 
 
 class NbConvertApp(BaseIPythonApplication):
-    """Application used to convert to and from notebook file type (*.ipynb)"""
+    """Application used to convert from notebook file type (``*.ipynb``)"""
 
     name = 'ipython-nbconvert'
     aliases = nbconvert_aliases

IPython/nbconvert/preprocessors/coalescestreams.py

@@ -18,8 +18,7 b' def cell_preprocessor(function):'
     """
     Wrap a function to be executed on all cells of a notebook
     
-    Wrapped Parameters
-    ------------------
+    The wrapped function should have these parameters:
     
     cell : NotebookNode cell
         Notebook cell being processed

IPython/nbconvert/tests/base.py

@@ -88,8 +88,8 b' class TestsBase(unittest.TestCase):'
            Replace "ii" with "i" in the string "Hiiii" yields "Hii"
            Another replacement cds "Hi" (the desired output)
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         text : string
             Text to replace in.
         search : string
@@ -141,8 +141,8 b' class TestsBase(unittest.TestCase):'
         Execute a, IPython shell command, listening for both Errors and non-zero
         return codes.
 
-        PARAMETERS:
-        -----------
+        Parameters
+        ----------
         parameters : str
             List of parameters to pass to IPython.
         ignore_return_code : optional bool (default False)

IPython/nbformat/convert.py

@@ -31,8 +31,8 b' def convert(nb, to_version):'
     a v4.  Also assumes that all conversions can be made in one step increments
     between major versions and ignores minor revisions.
 
-    PARAMETERS:
-    -----------
+    Parameters
+    ----------
     nb : NotebookNode
     to_version : int
         Major revision to convert the notebook to.  Can either be an upgrade or

IPython/nbformat/current.py

@@ -30,6 +30,7 b' from IPython.nbformat.v3 import ('
     parse_filename, new_metadata, new_author, new_heading_cell, nbformat,
     nbformat_minor, to_notebook_json
 )
+from IPython.nbformat import v3 as _v_latest
 
 from .reader import reads as reader_reads
 from .reader import versions
@@ -41,6 +42,16 b' from .convert import convert'
 
 current_nbformat = nbformat
 current_nbformat_minor = nbformat_minor
+current_nbformat_module = _v_latest.__name__
+
+def docstring_nbformat_mod(func):
+    """Decorator for docstrings referring to classes/functions accessed through
+    nbformat.current.
+
+    Put {nbformat_mod} in the docstring in place of 'IPython.nbformat.v3'.
+    """
+    func.__doc__ = func.__doc__.format(nbformat_mod=current_nbformat_module)
+    return func
 
 
 class NBFormatError(ValueError):

IPython/parallel/apps/launcher.py

@@ -1308,6 +1308,7 b' class HTCondorLauncher(BatchSystemLauncher):'
     this - the mechanism of shebanged scripts means that the python binary will be 
     launched with argv[0] set to the *location of the ip{cluster, engine, controller} 
     scripts on the remote node*. This means you need to take care that:
+
       a. Your remote nodes have their paths configured correctly, with the ipengine and ipcontroller
          of the python environment you wish to execute code in having top precedence.
       b. This functionality is untested on Windows.

IPython/parallel/client/magics.py

@@ -46,6 +46,7 b' from IPython.core.error import UsageError'
 from IPython.core.magic import Magics
 from IPython.core import magic_arguments
 from IPython.testing.skipdoctest import skip_doctest
+from IPython.utils.text import dedent
 
 #-----------------------------------------------------------------------------
 # Definitions of magic functions for use with IPython
@@ -108,11 +109,9 b' def output_args(f):'
             
             Choices are:
             
-            type: group outputs of all engines by type (stdout, stderr, displaypub, etc.).
-            
-            engine: display all output for each engine together.
-
-            order: like type, but individual displaypub output from each engine is collated.
+            **type**: group outputs of all engines by type (stdout, stderr, displaypub, etc.).
+            **engine**: display all output for each engine together.
+            **order**: like type, but individual displaypub output from each engine is collated.
                 For example, if multiple plots are generated by each engine, the first
                 figure of each engine will be displayed, then the second of each, etc.
             """
@@ -435,8 +434,8 b' class ParallelMagics(Magics):'
 
 
 __doc__ = __doc__.format(
-                AUTOPX_DOC = ' '*8 + ParallelMagics.autopx.__doc__,
-                PX_DOC = ' '*8 + ParallelMagics.px.__doc__,
-                RESULT_DOC = ' '*8 + ParallelMagics.result.__doc__,
-                CONFIG_DOC = ' '*8 + ParallelMagics.pxconfig.__doc__,
+                AUTOPX_DOC = dedent(ParallelMagics.autopx.__doc__),
+                PX_DOC = dedent(ParallelMagics.px.__doc__),
+                RESULT_DOC = dedent(ParallelMagics.result.__doc__),
+                CONFIG_DOC = dedent(ParallelMagics.pxconfig.__doc__),
 )

IPython/parallel/client/remotefunction.py

@@ -152,8 +152,10 b' class ParallelFunction(RemoteFunction):'
     dist : str [default: 'b']
         The key for which mapObject to use to distribute sequences
         options are:
+
           * 'b' : use contiguous chunks in order
           * 'r' : use round-robin striping
+
     block : bool [default: None]
         Whether to wait for results or not.  The default behavior is
         to use the current `block` attribute of `view`
@@ -162,7 +164,8 b' class ParallelFunction(RemoteFunction):'
     ordered : bool [default: True]
         Whether the result should be kept in order. If False,
         results become available as they arrive, regardless of submission order.
-    **flags : remaining kwargs are passed to View.temp_flags
+    **flags
+        remaining kwargs are passed to View.temp_flags
     """
 
     chunksize = None

IPython/parallel/client/view.py

@@ -221,30 +221,27 b' class View(HasTraits):'
         raise NotImplementedError("Implement in subclasses")
 
     def apply(self, f, *args, **kwargs):
-        """calls f(*args, **kwargs) on remote engines, returning the result.
+        """calls ``f(*args, **kwargs)`` on remote engines, returning the result.
 
         This method sets all apply flags via this View's attributes.
 
-        if self.block is False:
-            returns AsyncResult
-        else:
-            returns actual result of f(*args, **kwargs)
+        Returns :class:`~IPython.parallel.client.asyncresult.AsyncResult`
+        instance if ``self.block`` is False, otherwise the return value of
+        ``f(*args, **kwargs)``.
         """
         return self._really_apply(f, args, kwargs)
 
     def apply_async(self, f, *args, **kwargs):
-        """calls f(*args, **kwargs) on remote engines in a nonblocking manner.
+        """calls ``f(*args, **kwargs)`` on remote engines in a nonblocking manner.
 
-        returns AsyncResult
+        Returns :class:`~IPython.parallel.client.asyncresult.AsyncResult` instance.
         """
         return self._really_apply(f, args, kwargs, block=False)
 
     @spin_after
     def apply_sync(self, f, *args, **kwargs):
-        """calls f(*args, **kwargs) on remote engines in a blocking manner,
+        """calls ``f(*args, **kwargs)`` on remote engines in a blocking manner,
          returning the result.
-
-        returns: actual result of f(*args, **kwargs)
         """
         return self._really_apply(f, args, kwargs, block=True)
 
@@ -320,8 +317,7 b' class View(HasTraits):'
     def get_result(self, indices_or_msg_ids=None):
         """return one or more results, specified by history index or msg_id.
 
-        See client.get_result for details.
-
+        See :meth:`IPython.parallel.client.client.Client.get_result` for details.
         """
 
         if indices_or_msg_ids is None:
@@ -345,9 +341,9 b' class View(HasTraits):'
         raise NotImplementedError
 
     def map_async(self, f, *sequences, **kwargs):
-        """Parallel version of builtin `map`, using this view's engines.
+        """Parallel version of builtin :func:`python:map`, using this view's engines.
 
-        This is equivalent to map(...block=False)
+        This is equivalent to ``map(...block=False)``.
 
         See `self.map` for details.
         """
@@ -357,9 +353,9 b' class View(HasTraits):'
         return self.map(f,*sequences,**kwargs)
 
     def map_sync(self, f, *sequences, **kwargs):
-        """Parallel version of builtin `map`, using this view's engines.
+        """Parallel version of builtin :func:`python:map`, using this view's engines.
 
-        This is equivalent to map(...block=True)
+        This is equivalent to ``map(...block=True)``.
 
         See `self.map` for details.
         """
@@ -369,7 +365,7 b' class View(HasTraits):'
         return self.map(f,*sequences,**kwargs)
 
     def imap(self, f, *sequences, **kwargs):
-        """Parallel version of `itertools.imap`.
+        """Parallel version of :func:`itertools.imap`.
 
         See `self.map` for details.
 
@@ -575,7 +571,7 b' class DirectView(View):'
 
     @sync_results
     def map(self, f, *sequences, **kwargs):
-        """view.map(f, *sequences, block=self.block) => list|AsyncMapResult
+        """``view.map(f, *sequences, block=self.block)`` => list|AsyncMapResult
 
         Parallel version of builtin `map`, using this View's `targets`.
 
@@ -597,14 +593,14 b' class DirectView(View):'
         Returns
         -------
 
-        if block=False:
-            AsyncMapResult
+
+        If block=False
+          An :class:`~IPython.parallel.client.asyncresult.AsyncMapResult` instance.
                 An object like AsyncResult, but which reassembles the sequence of results
                 into a single list. AsyncMapResults can be iterated through before all
                 results are complete.
-        else:
-            list
-                the result of map(f,*sequences)
+        else
+            A list, the result of ``map(f,*sequences)``
         """
 
         block = kwargs.pop('block', self.block)
@@ -1056,7 +1052,7 b' class LoadBalancedView(View):'
     @sync_results
     @save_ids
     def map(self, f, *sequences, **kwargs):
-        """view.map(f, *sequences, block=self.block, chunksize=1, ordered=True) => list|AsyncMapResult
+        """``view.map(f, *sequences, block=self.block, chunksize=1, ordered=True)`` => list|AsyncMapResult
 
         Parallel version of builtin `map`, load-balanced by this View.
 
@@ -1091,14 +1087,13 b' class LoadBalancedView(View):'
         Returns
         -------
 
-        if block=False:
-            AsyncMapResult
+        if block=False
+          An :class:`~IPython.parallel.client.asyncresult.AsyncMapResult` instance.
                 An object like AsyncResult, but which reassembles the sequence of results
                 into a single list. AsyncMapResults can be iterated through before all
                 results are complete.
-            else:
-                the result of map(f,*sequences)
-
+        else
+            A list, the result of ``map(f,*sequences)``
         """
 
         # default

IPython/parallel/controller/dependency.py

@@ -105,8 +105,7 b' def require(*objects, **mapping):'
     and will be pushed to the engine with their __name__.
     Other objects can be passed by keyword arg.
     
-    Examples
-    --------
+    Examples::
     
     In [1]: @require('numpy')
        ...: def norm(a):

IPython/parallel/controller/dictdb.py

@@ -6,7 +6,8 b' Authors:'
 * Min RK
 
 
-TaskRecords are dicts of the form:
+TaskRecords are dicts of the form::
+
 {
     'msg_id' : str(uuid),
     'client_uuid' : str(uuid),
@@ -22,21 +23,25 b' TaskRecords are dicts of the form:'
     'result_content' : dict(content) or None,
     'result_buffers' : list(buffers) or None,
 }
-With this info, many of the special categories of tasks can be defined by query:
 
-pending:  completed is None
-client's outstanding: client_uuid = uuid && completed is None
-MIA: arrived is None (and completed is None)
-etc.
+With this info, many of the special categories of tasks can be defined by query,
+e.g.:
+
+* pending: completed is None
+* client's outstanding: client_uuid = uuid && completed is None
+* MIA: arrived is None (and completed is None)
+
+EngineRecords are dicts of the form::
 
-EngineRecords are dicts of the form:
 {
     'eid' : int(id),
     'uuid': str(uuid)
 }
+
 This may be extended, but is currently.
 
-We support a subset of mongodb operators:
+We support a subset of mongodb operators::
+
     $lt,$gt,$lte,$gte,$ne,$in,$nin,$all,$mod,$exists
 """
 #-----------------------------------------------------------------------------

IPython/parallel/controller/hub.py

@@ -1149,11 +1149,15 b' class Hub(SessionFactory):'
 
     def queue_status(self, client_id, msg):
         """Return the Queue status of one or more targets.
-        if verbose: return the msg_ids
-        else: return len of each type.
-        keys: queue (pending MUX jobs)
-            tasks (pending Task jobs)
-            completed (finished jobs from both queues)"""
+
+        If verbose, return the msg_ids, else return len of each type.
+
+        Keys:
+
+        * queue (pending MUX jobs)
+        * tasks (pending Task jobs)
+        * completed (finished jobs from both queues)
+        """
         content = msg['content']
         targets = content['targets']
         try:

IPython/parallel/util.py

@@ -199,7 +199,8 b' def disambiguate_url(url, location=None):'
     """turn multi-ip interfaces '0.0.0.0' and '*' into connectable
     ones, based on the location (default interpretation is localhost).
     
-    This is for zeromq urls, such as tcp://*:10101."""
+    This is for zeromq urls, such as ``tcp://*:10101``.
+    """
     try:
         proto,ip,port = split_url(url)
     except AssertionError:

IPython/qt/console/console_widget.py

@@ -236,8 +236,8 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
     def __init__(self, parent=None, **kw):
         """ Create a ConsoleWidget.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         parent : QWidget, optional [default None]
             The parent for this widget.
         """
@@ -543,8 +543,8 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
     def clear(self, keep_input=True):
         """ Clear the console.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         keep_input : bool, optional (default True)
             If set, restores the old input buffer if a new prompt is written.
         """
@@ -580,8 +580,8 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
         """ Executes source or the input buffer, possibly prompting for more
         input.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         source : str, optional
 
             The source to execute. If not specified, the input buffer will be
@@ -600,14 +600,14 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
             entered by the user. The effect of this parameter depends on the
             subclass implementation.
 
-        Raises:
-        -------
+        Raises
+        ------
         RuntimeError
             If incomplete input is given and 'hidden' is True. In this case,
             it is not possible to prompt for more input.
 
-        Returns:
-        --------
+        Returns
+        -------
         A boolean indicating whether the source was executed.
         """
         # WARNING: The order in which things happen here is very particular, in
@@ -746,8 +746,8 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
     def paste(self, mode=QtGui.QClipboard.Clipboard):
         """ Paste the contents of the clipboard into the input region.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         mode : QClipboard::Mode, optional [default QClipboard::Clipboard]
 
             Controls which part of the system clipboard is used. This can be
@@ -1060,8 +1060,8 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
         """ Given a KeyboardModifiers flags object, return whether the Control
         key is down.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         include_command : bool, optional (default True)
             Whether to treat the Command key as a (mutually exclusive) synonym
             for Control when in Mac OS.
@@ -1868,8 +1868,8 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
         """ Displays text using the pager if it exceeds the height of the
         viewport.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         html : bool, optional (default False)
             If set, the text will be interpreted as HTML instead of plain text.
         """
@@ -1903,11 +1903,8 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
         """
         Change the pager to `paging` style.
 
-        XXX: currently, this is limited to switching between 'hsplit' and
-        'vsplit'.
-
-        Parameters:
-        -----------
+        Parameters
+        ----------
         paging : string
             Either "hsplit", "vsplit", or "inside"
         """

IPython/qt/console/history_console_widget.py

@@ -155,15 +155,15 b' class HistoryConsoleWidget(ConsoleWidget):'
     def history_previous(self, substring='', as_prefix=True):
         """ If possible, set the input buffer to a previous history item.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         substring : str, optional
             If specified, search for an item with this substring.
         as_prefix : bool, optional
             If True, the substring must match at the beginning (default).
 
-        Returns:
-        --------
+        Returns
+        -------
         Whether the input buffer was changed.
         """
         index = self._history_index
@@ -186,15 +186,15 b' class HistoryConsoleWidget(ConsoleWidget):'
     def history_next(self, substring='', as_prefix=True):
         """ If possible, set the input buffer to a subsequent history item.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         substring : str, optional
             If specified, search for an item with this substring.
         as_prefix : bool, optional
             If True, the substring must match at the beginning (default).
 
-        Returns:
-        --------
+        Returns
+        -------
         Whether the input buffer was changed.
         """
         index = self._history_index
@@ -217,8 +217,8 b' class HistoryConsoleWidget(ConsoleWidget):'
     def history_tail(self, n=10):
         """ Get the local history list.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         n : int
             The (maximum) number of history items to get.
         """

IPython/qt/console/ipython_widget.py

@@ -438,8 +438,8 b' class IPythonWidget(FrontendWidget):'
     def set_default_style(self, colors='lightbg'):
         """ Sets the widget style to the class defaults.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         colors : str, optional (default lightbg)
             Whether to use the default IPython light background or dark
             background or B&W style.
@@ -464,8 +464,8 b' class IPythonWidget(FrontendWidget):'
     def _edit(self, filename, line=None):
         """ Opens a Python script for editing.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         filename : str
             A path to a local system file.
 

IPython/qt/console/kill_ring.py

@@ -32,8 +32,8 b' class KillRing(object):'
     def yank(self):
         """ Yank back the most recently killed text.
 
-        Returns:
-        --------
+        Returns
+        -------
         A text string or None.
         """
         self._index = len(self._ring)
@@ -42,8 +42,8 b' class KillRing(object):'
     def rotate(self):
         """ Rotate the kill ring, then yank back the new top.
 
-        Returns:
-        --------
+        Returns
+        -------
         A text string or None.
         """
         self._index -= 1

IPython/qt/console/mainwindow.py

@@ -673,8 +673,8 b' class MainWindow(QtGui.QMainWindow):'
     def _get_magic_menu(self,menuidentifier, menulabel=None):
         """return a submagic menu by name, and create it if needed
        
-        parameters:
-        -----------
+        Parameters
+        ----------
 
         menulabel : str
             Label for the menu

IPython/qt/console/qtconsoleapp.py

@@ -36,6 +36,10 b' import sys'
 if os.name == 'nt':
     old_excepthook = sys.excepthook
 
+    # Exclude this from our autogenerated API docs.
+    undoc = lambda func: func
+
+    @undoc
     def gui_excepthook(exctype, value, tb):
         try:
             import ctypes, traceback

IPython/qt/rich_text.py

@@ -126,8 +126,8 b' class HtmlExporter(object):'
 def export_html(html, filename, image_tag = None, inline = True):
     """ Export the contents of the ConsoleWidget as HTML.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     html : unicode,
         A Python unicode string containing the Qt HTML to export.
 
@@ -162,8 +162,8 b' def export_html(html, filename, image_tag = None, inline = True):'
 def export_xhtml(html, filename, image_tag=None):
     """ Export the contents of the ConsoleWidget as XHTML with inline SVGs.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     html : unicode,
         A Python unicode string containing the Qt HTML to export.
 
@@ -216,8 +216,8 b' def default_image_tag(match, path = None, format = "png"):'
 def fix_html(html):
     """ Transforms a Qt-generated HTML string into a standards-compliant one.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     html : unicode,
         A Python unicode string containing the Qt HTML.
     """

IPython/qt/svg.py

@@ -10,16 +10,16 b' from IPython.utils.py3compat import unicode_type'
 def save_svg(string, parent=None):
     """ Prompts the user to save an SVG document to disk.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     string : basestring
         A Python string containing a SVG document.
 
     parent : QWidget, optional
         The parent to use for the file dialog.
 
-    Returns:
-    --------
+    Returns
+    -------
     The name of the file to which the document was saved, or None if the save
     was cancelled.
     """
@@ -43,8 +43,8 b' def save_svg(string, parent=None):'
 def svg_to_clipboard(string):
     """ Copy a SVG document to the clipboard.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     string : basestring
         A Python string containing a SVG document.
     """
@@ -58,8 +58,8 b' def svg_to_clipboard(string):'
 def svg_to_image(string, size=None):
     """ Convert a SVG document to a QImage.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
     string : basestring
         A Python string containing a SVG document.
 
@@ -67,13 +67,13 b' def svg_to_image(string, size=None):'
         The size of the image that is produced. If not specified, the SVG
         document's default size is used.
     
-    Raises:
-    -------
+    Raises
+    ------
     ValueError
         If an invalid SVG string is provided.
 
-    Returns:
-    --------
+    Returns
+    -------
     A QImage of format QImage.Format_ARGB32.
     """
     if isinstance(string, unicode_type):

IPython/sphinxext/ipython_directive.py

@@ -31,7 +31,6 b' ipython_promptin:'
     The default is 'In [%d]:'. This expects that the line numbers are used
     in the prompt.
 ipython_promptout:
-
     The string to represent the IPython prompt in the generated ReST. The
     default is 'Out [%d]:'. This expects that the line numbers are used
     in the prompt.

IPython/terminal/embed.py

@@ -161,30 +161,28 b' class InteractiveShellEmbed(TerminalInteractiveShell):'
                  display_banner=None, global_ns=None, compile_flags=None):
         """Embeds IPython into a running python program.
 
-        Input:
-
-          - header: An optional header message can be specified.
-
-          - local_ns, module: working local namespace (a dict) and module (a
-          module or similar object). If given as None, they are automatically
-          taken from the scope where the shell was called, so that
-          program variables become visible.
-
-          - stack_depth: specifies how many levels in the stack to go to
-          looking for namespaces (when local_ns or module is None).  This
-          allows an intermediate caller to make sure that this function gets
-          the namespace from the intended level in the stack.  By default (0)
-          it will get its locals and globals from the immediate caller.
-
-          - compile_flags: A bit field identifying the __future__ features
-          that are enabled, as passed to the builtin `compile` function. If
-          given as None, they are automatically taken from the scope where the
-          shell was called.
-
-        Warning: it's possible to use this in a program which is being run by
-        IPython itself (via %run), but some funny things will happen (a few
-        globals get overwritten). In the future this will be cleaned up, as
-        there is no fundamental reason why it can't work perfectly."""
+        Parameters
+        ----------
+
+        local_ns, module
+          Working local namespace (a dict) and module (a module or similar
+          object). If given as None, they are automatically taken from the scope
+          where the shell was called, so that program variables become visible.
+
+        stack_depth : int
+          How many levels in the stack to go to looking for namespaces (when
+          local_ns or module is None). This allows an intermediate caller to
+          make sure that this function gets the namespace from the intended
+          level in the stack. By default (0) it will get its locals and globals
+          from the immediate caller.
+
+        compile_flags
+          A bit field identifying the __future__ features
+          that are enabled, as passed to the builtin :func:`compile` function.
+          If given as None, they are automatically taken from the scope where
+          the shell was called.
+
+        """
         
         if (global_ns is not None) and (module is None):
             warnings.warn("global_ns is deprecated, use module instead.", DeprecationWarning)

IPython/terminal/interactiveshell.py

@@ -191,8 +191,7 b' class TerminalMagics(Magics):'
         This assigns the pasted block to variable 'foo' as string, without
         executing it (preceding >>> and + is still stripped).
 
-        Options
-        -------
+        Options:
 
           -r: re-executes the block previously entered by cpaste.
 
@@ -561,12 +560,11 b' class TerminalInteractiveShell(InteractiveShell):'
         The returned line does not include the trailing newline.
         When the user enters the EOF key sequence, EOFError is raised.
 
-        Optional inputs:
+        Parameters
+        ----------
 
-          - prompt(''): a string to be printed to prompt the user.
-
-          - continue_prompt(False): whether this line is the first one or a
-          continuation in a sequence of inputs.
+        prompt : str, optional
+          A string to be printed to prompt the user.
         """
         # Code run by the user may have modified the readline completer state.
         # We must ensure that our completer is back in place.

IPython/testing/decorators.py

@@ -175,13 +175,14 b' def skipif(skip_condition, msg=None):'
 
     Parameters
     ----------
-    skip_condition : bool or callable.
+
+    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
         is useful for tests that may require costly imports, to delay the cost
         until the test suite is actually executed.
     msg : string
-        Message to give on raising a SkipTest exception
+      Message to give on raising a SkipTest exception.
 
    Returns
    -------

IPython/testing/tools.py

@@ -59,7 +59,7 b' def full_path(startPath,files):'
     """Make full paths for all the listed files, based on startPath.
 
     Only the base part of startPath is kept, since this routine is typically
-    used with a script's __file__ variable as startPath.  The base of startPath
+    used with a script's ``__file__`` variable as startPath. The base of startPath
     is then prepended to all the listed files, forming the output list.
 
     Parameters
@@ -80,7 +80,8 b' def full_path(startPath,files):'
     >>> full_path('/foo',['a.txt','b.txt'])
     ['/a.txt', '/b.txt']
 
-    If a single file is given, the output is still a list:
+    If a single file is given, the output is still a list::
+
     >>> full_path('/foo','a.txt')
     ['/a.txt']
     """
@@ -105,7 +106,8 b' def parse_test_output(txt):'
 
     Returns
     -------
-    nerr, nfail: number of errors and failures.
+    nerr, nfail
+      number of errors and failures.
     """
 
     err_m = re.search(r'^FAILED \(errors=(\d+)\)', txt, re.MULTILINE)

IPython/utils/attic.py

@@ -81,7 +81,8 b' def belong(candidates,checklist):'
 def with_obj(object, **args):
     """Set multiple attributes for an object, similar to Pascal's with.
 
-    Example:
+    Example::
+
     with_obj(jim,
              born = 1960,
              haircolour = 'Brown',

IPython/utils/coloransi.py

@@ -48,8 +48,9 b' color_templates = ('
 def make_color_table(in_class):
     """Build a set of color attributes in a class.
 
-    Helper function for building the *TermColors classes."""
-
+    Helper function for building the :class:`TermColors` and
+    :class`InputTermColors`.
+    """
     for name,value in color_templates:
         setattr(in_class,name,in_class._base % value)
 

IPython/utils/frame.py

@@ -26,17 +26,20 b' from IPython.utils import py3compat'
 def extract_vars(*names,**kw):
     """Extract a set of variables by name from another frame.
 
-    :Parameters:
-      - `*names`: strings
+    Parameters
+    ----------
+    *names : str
         One or more variable names which will be extracted from the caller's
     frame.
 
-    :Keywords:
-      - `depth`: integer (0)
+    depth : integer, optional
         How many frames in the stack to walk when looking for your variables.
+        The default is 0, which will use the frame where the call was made.
 
 
-    Examples:
+    Examples
+    --------
+    ::
 
         In [2]: def func(x):
            ...:     y = 1

IPython/utils/text.py

@@ -110,10 +110,10 b' class SList(list):'
 
     These are normal lists, but with the special attributes:
 
-        .l (or .list) : value as list (the list itself).
-        .n (or .nlstr): value as a string, joined on newlines.
-        .s (or .spstr): value as a string, joined on spaces.
-        .p (or .paths): list of path objects
+    * .l (or .list) : value as list (the list itself).
+    * .n (or .nlstr): value as a string, joined on newlines.
+    * .s (or .spstr): value as a string, joined on spaces.
+    * .p (or .paths): list of path objects
 
     Any values which require transformations are computed only once and
     cached."""
@@ -191,13 +191,14 b' class SList(list):'
         Allows quick awk-like usage of string lists.
 
         Example data (in var a, created by 'a = !ls -l')::
+
             -rwxrwxrwx  1 ville None      18 Dec 14  2006 ChangeLog
             drwxrwxrwx+ 6 ville None       0 Oct 24 18:05 IPython
 
-        a.fields(0) is ['-rwxrwxrwx', 'drwxrwxrwx+']
-        a.fields(1,0) is ['1 -rwxrwxrwx', '6 drwxrwxrwx+']
+        * ``a.fields(0)`` is ``['-rwxrwxrwx', 'drwxrwxrwx+']``
+        * ``a.fields(1,0)`` is ``['1 -rwxrwxrwx', '6 drwxrwxrwx+']``
         (note the joining by space).
-        a.fields(-1) is ['ChangeLog', 'IPython']
+        * ``a.fields(-1)`` is ``['ChangeLog', 'IPython']``
 
         IndexErrors are ignored.
 

IPython/utils/traitlets.py

@@ -761,8 +761,8 b' class Instance(ClassBasedTraitType):'
         allow_none : bool
             Indicates whether None is allowed as a value.
 
-        Default Value
-        -------------
+        Notes
+        -----
         If both ``args`` and ``kw`` are None, then the default value is None.
         If ``args`` is a tuple and ``kw`` is a dict, then the default is
         created as ``klass(*args, **kw)``.  If either ``args`` or ``kw`` is

docs/autogen_api.py

@@ -17,45 +17,29 b" if __name__ == '__main__':"
     docwriter = ApiDocWriter(package,rst_extension='.rst')
     # You have to escape the . here because . is a special char for regexps.
     # You must do make clean if you change this!
-    docwriter.package_skip_patterns += [r'\.fixes$',
-                                        r'\.external$',
+    docwriter.package_skip_patterns += [r'\.external$',
+                                        # Extensions are documented elsewhere.
                                         r'\.extensions',
-                                        r'\.kernel\.config',
-                                        r'\.attic',
-                                        r'\.quarantine',
-                                        r'\.deathrow',
-                                        r'\.config\.default',
                                         r'\.config\.profile',
-                                        r'\.frontend',
-                                        r'\.gui',
-                                        r'\.kernel',
-                                        # For now, the zmq code has
-                                        # unconditional top-level code so it's
-                                        # not import safe.  This needs fixing
-                                        r'\.zmq',
                                         ]
 
-    docwriter.module_skip_patterns += [
-                                        r'\.testing\.iptest',
-                                        # Keeping these disabled is OK
-                                        r'\.parallel\.controller\.mongodb',
-                                        r'\.lib\.inputhookwx',
-                                        r'\.lib\.inputhookgtk',
-                                        r'\.cocoa',
+    # The inputhook* modules often cause problems on import, such as trying to
+    # load incompatible Qt bindings. It's easiest to leave them all out. The
+    # main API is in the inputhook module, which is documented.
+    docwriter.module_skip_patterns += [ r'\.lib\.inputhook.+',
                                         r'\.ipdoctest',
-                                        r'\.Gnuplot',
-                                        r'\.frontend\.process\.winprocess',
+                                        r'\.testing\.plugin',
+                                        # This just prints a deprecation msg:
                                         r'\.frontend',
-                                        r'\.Shell',
                                         ]
     
-    # If we don't have pexpect, we can't load irunner, so skip any code that
-    # depends on it
+    # We're rarely working on machines with the Azure SDK installed, so we
+    # skip the module that needs it in that case.
     try:
-        import pexpect
+        import azure  # analysis:ignore
     except ImportError:
-        docwriter.module_skip_patterns += [r'\.lib\.irunner',
-                                           r'\.testing\.mkdoctests']
+        docwriter.module_skip_patterns.append(r'\.html\.services\.notebooks\.azurenbmanager')
+
     # Now, generate the outputs
     docwriter.write_api_docs(outdir)
     # Write index with .txt extension - we can include it, but Sphinx won't try

docs/source/conf.py

@@ -44,6 +44,7 b' extensions = ['
     'matplotlib.sphinxext.only_directives',
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.intersphinx',
@@ -179,7 +180,7 b' html_additional_pages = {'
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ipythondoc'
 
-intersphinx_mapping = {'http://docs.python.org/2/': None}
+intersphinx_mapping = {'python': ('http://docs.python.org/2/', None)}
 
 # Options for LaTeX output
 # ------------------------

docs/source/development/gitwash/development_workflow.rst

@@ -116,8 +116,7 b' The generated comparison, is between your feature branch'
 ``my-new-feature``, and the place in ``master`` from which you branched
 ``my-new-feature``.  In other words, you can keep updating ``master``
 without interfering with the output from the comparison.  More detail?
-Note the three dots in the URL above (``master...my-new-feature``) and
-see :ref:`dot2-dot3`.
+Note the three dots in the URL above (``master...my-new-feature``).
 
 Asking for your changes to be merged with the main repo
 =======================================================

docs/source/development/index.rst

@@ -26,3 +26,4 b' on the IPython GitHub wiki.'
    parallel_connections
    pycompat
    config
+   inputhook_app

docs/source/whatsnew/github-stats-0.12.rst

@@ -140,7 +140,7 b' Pull requests (257):'
 * `1126 <https://github.com/ipython/ipython/issues/1126>`_: Totally remove pager when read only (notebook)
 * `1091 <https://github.com/ipython/ipython/issues/1091>`_: qtconsole : allow copy with shortcut in pager
 * `1114 <https://github.com/ipython/ipython/issues/1114>`_: fix magics history in two-process ipython console
-* `1113 <https://github.com/ipython/ipython/issues/1113>`_: Fixing #1112 removing failing asserts for test_carriage_return and test_...
+* `1113 <https://github.com/ipython/ipython/issues/1113>`_: Fixing #1112 removing failing asserts for test_carriage_return and test_beep
 * `1089 <https://github.com/ipython/ipython/issues/1089>`_: Support carriage return ('\r') and beep ('\b') characters in the qtconsole
 * `1108 <https://github.com/ipython/ipython/issues/1108>`_: Completer usability 2 (rebased of  pr #1082)
 * `864 <https://github.com/ipython/ipython/issues/864>`_: Two-process terminal frontend (ipython core branch)

docs/source/whatsnew/github-stats-1.0.rst

@@ -643,7 +643,7 b' Pull Requests (793):'
 * :ghpull:`3223`: add missing mathjax_url to new settings dict
 * :ghpull:`3089`: add stdin to the notebook
 * :ghpull:`3221`: Remove references to HTMLCell (dead code)
-* :ghpull:`3205`: add ignored *args to HasTraits constructor
+* :ghpull:`3205`: add ignored ``*args`` to HasTraits constructor
 * :ghpull:`3088`: cleanup IPython handler settings
 * :ghpull:`3201`: use much faster regexp for ansi coloring
 * :ghpull:`3220`: avoid race condition in profile creation
@@ -1064,7 +1064,7 b' Pull Requests (793):'
 * :ghpull:`2140`: 2to3: Apply `has_key` fixer.
 * :ghpull:`2131`: Add option append (-a) to %save
 * :ghpull:`2117`: use explicit url in notebook example
-* :ghpull:`2133`: Tell git that *.py files contain Python code, for use in word-diffs.
+* :ghpull:`2133`: Tell git that ``*.py`` files contain Python code, for use in word-diffs.
 * :ghpull:`2134`: Apply 2to3 `next` fix.
 * :ghpull:`2126`: ipcluster broken with any batch launcher (PBS/LSF/SGE)
 * :ghpull:`2104`: Windows make file for Sphinx documentation
@@ -1423,7 +1423,7 b' Issues (691):'
 * :ghissue:`3207`: [Feature] folders for ipython notebook dashboard
 * :ghissue:`3178`: cell magics do not work with empty lines after #2447
 * :ghissue:`3204`: Default plot() colors unsuitable for red-green colorblind users
-* :ghissue:`1789`: :\n/*foo turns into :\n*(foo) in triple-quoted strings.
+* :ghissue:`1789`: ``:\n/*foo`` turns into ``:\n*(foo)`` in triple-quoted strings.
 * :ghissue:`3202`: File cell magic fails with blank lines
 * :ghissue:`3199`: %%cython -a stopped working?
 * :ghissue:`2688`: obsolete imports in import autocompletion
@@ -1649,7 +1649,7 b' Issues (691):'
 * :ghissue:`1308`: ipython qtconsole  --ssh=server --existing ... hangs
 * :ghissue:`1679`: List command doesn't work in ipdb debugger the first time
 * :ghissue:`2545`: pypi win32 installer creates 64bit executibles
-* :ghissue:`2080`: Event loop issues with IPython 0.12 and PyQt4 (QDialog.exec_ and more)
+* :ghissue:`2080`: Event loop issues with IPython 0.12 and PyQt4 (``QDialog.exec_`` and more)
 * :ghissue:`2541`: Allow `python -m IPython`
 * :ghissue:`2508`: subplots_adjust() does not work correctly in ipython notebook
 * :ghissue:`2289`: Incorrect mathjax rendering of certain arrays of equations

docs/source/whatsnew/version0.11.rst

@@ -547,7 +547,7 b' Backwards incompatible changes'
 
 * Old style configuration files :file:`ipythonrc` and :file:`ipy_user_conf.py`
   are no longer supported. Users should migrate there configuration files to
-  the new format described :doc:`here <config/intro>` and
+  the new format described :doc:`here </config/intro>` and
   :ref:`here <config_overview>`.
 
 * The old IPython extension API that relied on :func:`ipapi` has been

docs/sphinxext/apigen.py

@@ -220,7 +220,7 b' class ApiDocWriter(object):'
         # get the names of all classes and functions
         functions, classes = self._parse_module(uri)
         if not len(functions) and not len(classes):
-            print ('WARNING: Empty -', uri)  # dbg
+            #print ('WARNING: Empty -', uri)  # dbg
             return ''
 
         # Make a shorter version of the uri that omits the package name for
@@ -415,7 +415,8 b' class ApiDocWriter(object):'
         idx = open(path,'wt')
         w = idx.write
         w('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
-        w('.. toctree::\n\n')
-        for f in self.written_modules:
-            w('   %s\n' % os.path.join(relpath,f))
+        w('.. autosummary::\n'
+          '   :toctree: %s\n\n' % relpath)
+        for mod in self.written_modules:
+            w('   %s\n' % mod)
         idx.close()