More fixes to doc formatting

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/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:

IPython/kernel/zmq/zmqshell.py

@@ -197,116 +197,116 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.
-
-        -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.
-
+        -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
+          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.
+          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).
+          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.
+          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.
+          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.
+          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.
+          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
+        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:
+        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'
+            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():
+        We can then call the function foo()::
 
-        In [2]: foo()
-        foo() was defined in an editing session
+            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:
+        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...
+            In [3]: ed foo
+            Editing... done. Executing edited code...
 
-        And if we call foo() again we get the modified version:
+        And if we call foo() again we get the modified version::
 
-        In [4]: foo()
-        foo() has now been changed!
+            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:
+        times. First we call the editor::
 
-        In [5]: ed
-        Editing... done. Executing edited code...
-        hello
-        Out[5]: "print 'hello'n"
+            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 _):
+        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"
+            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]):
+        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"
+            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

@@ -360,13 +360,14 b' class BackgroundJobBase(threading.Thread):'
     The derived classes must implement:
 
     - Their own __init__, since the one here raises NotImplementedError.  The
-    derived constructor must call self._init() at the end, to provide common
-    initialization.
+      derived constructor must call self._init() at the end, to provide common
+      initialization.
 
     - 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/nbconvert/exporters/exporter.py

@@ -103,10 +103,13 b' class Exporter(LoggingConfigurable):'
 
         Parameters
         ----------
-        nb : Notebook node
-        resources : dict (**kw)
-            of additional resources that can be accessed read/write by
-            preprocessors.
+        nb : :class:`~IPython.nbformat.v3.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

@@ -193,10 +193,11 b' class TemplateExporter(Exporter):'
     
         Parameters
         ----------
-        nb : Notebook node
-        resources : dict (**kw) 
-            of additional resources that can be accessed read/write by 
-            preprocessors and filters.
+        nb : :class:`~IPython.nbformat.v3.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/parallel/apps/launcher.py

@@ -1308,9 +1308,10 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.
+
+    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.
 
     If you need different behavior, consider making you own template.
     """

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/utils/attic.py

@@ -81,11 +81,12 b' def belong(candidates,checklist):'
 def with_obj(object, **args):
     """Set multiple attributes for an object, similar to Pascal's with.
 
-    Example:
-    with_obj(jim,
-             born = 1960,
-             haircolour = 'Brown',
-             eyecolour = 'Green')
+    Example::
+
+        with_obj(jim,
+                 born = 1960,
+                 haircolour = 'Brown',
+                 eyecolour = 'Green')
 
     Credit: Greg Ewing, in
     http://mail.python.org/pipermail/python-list/2001-May/040703.html.