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,31 +197,31 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
+        -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 +237,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.
 
@@ -258,50 +258,50 b' class KernelMagics(Magics):'
         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'
 
-        We can then call the function foo():
+        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:
+        (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:
+        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:
+        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 _):
+        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]):
+        Now we call it with the output #8 (stored in ``_8``, also as Out[8])::
 
         In [7]: ed _8
         Editing... done. Executing edited code...

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/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,9 +193,10 b' class TemplateExporter(Exporter):'
     
         Parameters
         ----------
-        nb : Notebook node
-        resources : dict (**kw) 
-            of additional resources that can be accessed read/write by 
+        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,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/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,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',