Miscellaneous docs fixes

IPython/core/inputsplitter.py

@@ -212,13 +212,13 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
-       code could be executed already. In addition, it provides a method called
-       :meth:`push_accepts_more` that can be used to query whether more input
-       can be pushed into a single interactive block.
+    :meth:`push`. It will return on each push whether the currently pushed
+    code could be executed already. In addition, it provides a method called
+    :meth:`push_accepts_more` that can be used to query whether more input
+    can be pushed into a single interactive block.
 
     This is a simple example of how an interactive terminal-based client can use
     this tool::

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

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/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/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:`~IPython.nbformat.v3.nbbase.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,6 +57,8 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
     """
             
@@ -92,11 +96,13 b' def export(exporter, nb, **kw):'
     """
     Export a notebook object using specific exporter class.
     
-    exporter : Exporter class type 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 
-        signature as the base Exporter class.
+    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
+      signature as the base Exporter class.
     """
     
     #Check arguments
@@ -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/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