Merge pull request #4220 from takluyver/docs-shotgun-1

Various improvements to docs formatting

Clearing up some of the broken formatting in the docs, in no particular order.

IPython/core/completer.py

@@ -24,26 +24,26 b' Tip: to use the tab key as the completion key, call'
 Notes:
 
 - Exceptions raised by the completer function are *ignored* (and
-generally cause the completion to fail).  This is a feature -- since
-readline sets the tty device in raw (or cbreak) mode, printing a
-traceback wouldn't work well without some complicated hoopla to save,
-reset and restore the tty state.
+  generally cause the completion to fail).  This is a feature -- since
+  readline sets the tty device in raw (or cbreak) mode, printing a
+  traceback wouldn't work well without some complicated hoopla to save,
+  reset and restore the tty state.
 
 - The evaluation of the NAME.NAME... form may cause arbitrary
-application defined code to be executed if an object with a
-__getattr__ hook is found.  Since it is the responsibility of the
-application (or the user) to enable this feature, I consider this an
-acceptable risk.  More complicated expressions (e.g. function calls or
-indexing operations) are *not* evaluated.
+  application defined code to be executed if an object with a
+  ``__getattr__`` hook is found.  Since it is the responsibility of the
+  application (or the user) to enable this feature, I consider this an
+  acceptable risk.  More complicated expressions (e.g. function calls or
+  indexing operations) are *not* evaluated.
 
 - GNU readline is also used by the built-in functions input() and
-raw_input(), and thus these also benefit/suffer from the completer
-features.  Clearly an interactive application can benefit by
-specifying its own completer function and using raw_input() for all
-its input.
+  raw_input(), and thus these also benefit/suffer from the completer
+  features.  Clearly an interactive application can benefit by
+  specifying its own completer function and using raw_input() for all
+  its input.
 
 - When the original stdin is not a tty device, GNU readline is never
-used, and this module (and the readline module) are silently inactive.
+  used, and this module (and the readline module) are silently inactive.
 """
 
 #*****************************************************************************
@@ -441,17 +441,17 b' class IPCompleter(Completer):'
         Inputs:
 
         - shell: a pointer to the ipython shell itself.  This is needed
-        because this completer knows about magic functions, and those can
-        only be accessed via the ipython instance.
+          because this completer knows about magic functions, and those can
+          only be accessed via the ipython instance.
 
         - namespace: an optional dict where completions are performed.
 
         - global_namespace: secondary optional dict for completions, to
-        handle cases (such as IPython embedded inside functions) where
-        both Python scopes are visible.
+          handle cases (such as IPython embedded inside functions) where
+          both Python scopes are visible.
 
         - If alias_table is supplied, it should be a dictionary of aliases
-        to complete.
+          to complete.
 
         use_readline : bool, optional
           If true, use the readline library.  This completer can still function

IPython/core/debugger.py

@@ -96,19 +96,24 b' class Tracer(object):'
     def __init__(self,colors=None):
         """Create a local debugger instance.
 
-        :Parameters:
+        Parameters
+        ----------
 
-          - `colors` (None): a string containing the name of the color scheme to
-        use, it must be one of IPython's valid color schemes.  If not given, the
-        function will default to the current IPython scheme when running inside
-        IPython, and to 'NoColor' otherwise.
+        colors : str, optional
+            The name of the color scheme to use, it must be one of IPython's
+            valid color schemes.  If not given, the function will default to
+            the current IPython scheme when running inside IPython, and to
+            'NoColor' otherwise.
 
-        Usage example:
+        Examples
+        --------
+        ::
 
-        from IPython.core.debugger import Tracer; debug_here = Tracer()
+            from IPython.core.debugger import Tracer; debug_here = Tracer()
 
-        ... later in your code
-        debug_here()  # -> will open up the debugger at that point.
+        Later in your code::
+        
+            debug_here()  # -> will open up the debugger at that point.
 
         Once the debugger activates, you can use all of its regular commands to
         step through code, set breakpoints, etc.  See the pdb documentation

IPython/core/interactiveshell.py

@@ -916,9 +916,9 b' class InteractiveShell(SingletonConfigurable):'
         Keywords:
 
           - force(False): by default, this routine checks the instance call_pdb
-          flag and does not actually invoke the debugger if the flag is false.
-          The 'force' option forces the debugger to activate even if the flag
-          is false.
+            flag and does not actually invoke the debugger if the flag is false.
+            The 'force' option forces the debugger to activate even if the flag
+            is false.
         """
 
         if not (force or self.call_pdb):
@@ -2987,7 +2987,7 b' class InteractiveShell(SingletonConfigurable):'
         Optional inputs:
 
           - data(None): if data is given, it gets written out to the temp file
-          immediately, and the file is closed again."""
+            immediately, and the file is closed again."""
 
         filename = tempfile.mktemp('.py', prefix)
         self.tempfiles.append(filename)
@@ -3030,13 +3030,14 b' class InteractiveShell(SingletonConfigurable):'
 
         Optional Parameters:
           - raw(False): by default, the processed input is used.  If this is
-          true, the raw input history is used instead.
+            true, the raw input history is used instead.
 
         Note that slices can be called with two notations:
 
         N:M -> standard python form, means including items N...(M-1).
 
-        N-M -> include items N..M (closed endpoint)."""
+        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/logger.py

@@ -171,11 +171,11 b' which already exists. But you must first start the logging process with'
         Inputs:
 
         - line_mod: possibly modified input, such as the transformations made
-        by input prefilters or input handlers of various kinds.  This should
-        always be valid Python.
+          by input prefilters or input handlers of various kinds. This should
+          always be valid Python.
 
-        - line_ori: unmodified input line from the user.  This is not
-        necessarily valid Python.
+        - line_ori: unmodified input line from the user. This is not
+          necessarily valid Python.
         """
 
         # Write the log line, but decide which one according to the

IPython/core/magic.py

@@ -489,11 +489,11 b' class Magics(object):'
     MUST:
 
     - Use the method decorators `@line_magic` and `@cell_magic` to decorate
-    individual methods as magic functions, AND
+      individual methods as magic functions, AND
 
     - Use the class decorator `@magics_class` to ensure that the magic
-    methods are properly registered at the instance level upon instance
-    initialization.
+      methods are properly registered at the instance level upon instance
+      initialization.
 
     See :mod:`magic_functions` for examples of actual implementation classes.
     """

IPython/core/magics/execution.py

@@ -102,75 +102,84 b' python-profiler package from non-free.""")'
 
         Options:
 
-        -l <limit>: you can place restrictions on what or how much of the
-        profile gets printed. The limit value can be:
-
-          * A string: only information for function names containing this string
-          is printed.
-
-          * An integer: only these many lines are printed.
-
-          * A float (between 0 and 1): this fraction of the report is printed
-          (for example, use a limit of 0.4 to see the topmost 40% only).
-
-        You can combine several limits with repeated use of the option. For
-        example, '-l __init__ -l 5' will print only the topmost 5 lines of
-        information about class constructors.
-
-        -r: return the pstats.Stats object generated by the profiling. This
-        object has all the information about the profile in it, and you can
-        later use it for further analysis or in other functions.
-
-       -s <key>: sort profile by given key. You can provide more than one key
-        by using the option several times: '-s key1 -s key2 -s key3...'. The
-        default sorting key is 'time'.
-
-        The following is copied verbatim from the profile documentation
-        referenced below:
-
-        When more than one key is provided, additional keys are used as
-        secondary criteria when the there is equality in all keys selected
-        before them.
-
-        Abbreviations can be used for any key names, as long as the
-        abbreviation is unambiguous.  The following are the keys currently
-        defined:
-
-                Valid Arg       Meaning
-                  "calls"      call count
-                  "cumulative" cumulative time
-                  "file"       file name
-                  "module"     file name
-                  "pcalls"     primitive call count
-                  "line"       line number
-                  "name"       function name
-                  "nfl"        name/file/line
-                  "stdname"    standard name
-                  "time"       internal time
-
-        Note that all sorts on statistics are in descending order (placing
-        most time consuming items first), where as name, file, and line number
-        searches are in ascending order (i.e., alphabetical). The subtle
-        distinction between "nfl" and "stdname" is that the standard name is a
-        sort of the name as printed, which means that the embedded line
-        numbers get compared in an odd way.  For example, lines 3, 20, and 40
-        would (if the file names were the same) appear in the string order
-        "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
-        line numbers.  In fact, sort_stats("nfl") is the same as
-        sort_stats("name", "file", "line").
-
-        -T <filename>: save profile results as shown on screen to a text
-        file. The profile is still shown on screen.
-
-        -D <filename>: save (via dump_stats) profile statistics to given
-        filename. This data is in a format understood by the pstats module, and
-        is generated by a call to the dump_stats() method of profile
-        objects. The profile is still shown on screen.
-
-        -q: suppress output to the pager.  Best used with -T and/or -D above.
+        -l <limit>
+          you can place restrictions on what or how much of the
+          profile gets printed. The limit value can be:
+
+             * A string: only information for function names containing this string
+               is printed.
+
+             * An integer: only these many lines are printed.
+
+             * A float (between 0 and 1): this fraction of the report is printed
+               (for example, use a limit of 0.4 to see the topmost 40% only).
+
+          You can combine several limits with repeated use of the option. For
+          example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
+          information about class constructors.
+
+        -r
+          return the pstats.Stats object generated by the profiling. This
+          object has all the information about the profile in it, and you can
+          later use it for further analysis or in other functions.
+
+        -s <key>
+          sort profile by given key. You can provide more than one key
+          by using the option several times: '-s key1 -s key2 -s key3...'. The
+          default sorting key is 'time'.
+
+          The following is copied verbatim from the profile documentation
+          referenced below:
+
+          When more than one key is provided, additional keys are used as
+          secondary criteria when the there is equality in all keys selected
+          before them.
+
+          Abbreviations can be used for any key names, as long as the
+          abbreviation is unambiguous.  The following are the keys currently
+          defined:
+
+          ============  =====================
+          Valid Arg     Meaning
+          ============  =====================
+          "calls"       call count
+          "cumulative"  cumulative time
+          "file"        file name
+          "module"      file name
+          "pcalls"      primitive call count
+          "line"        line number
+          "name"        function name
+          "nfl"         name/file/line
+          "stdname"     standard name
+          "time"        internal time
+          ============  =====================
+
+          Note that all sorts on statistics are in descending order (placing
+          most time consuming items first), where as name, file, and line number
+          searches are in ascending order (i.e., alphabetical). The subtle
+          distinction between "nfl" and "stdname" is that the standard name is a
+          sort of the name as printed, which means that the embedded line
+          numbers get compared in an odd way.  For example, lines 3, 20, and 40
+          would (if the file names were the same) appear in the string order
+          "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
+          line numbers.  In fact, sort_stats("nfl") is the same as
+          sort_stats("name", "file", "line").
+
+        -T <filename>
+          save profile results as shown on screen to a text
+          file. The profile is still shown on screen.
+
+        -D <filename>
+          save (via dump_stats) profile statistics to given
+          filename. This data is in a format understood by the pstats module, and
+          is generated by a call to the dump_stats() method of profile
+          objects. The profile is still shown on screen.
+
+        -q
+          suppress output to the pager.  Best used with -T and/or -D above.
 
         If you want to run complete programs under the profiler's control, use
-        '%run -p [prof_opts] filename.py [args to program]' where prof_opts
+        ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
         contains profiler specific options as described here.
 
         You can read the complete documentation for the profile module with::
@@ -362,7 +371,8 b' python-profiler package from non-free.""")'
                   file_finder=get_py_filename):
         """Run the named file inside IPython as a program.
 
-        Usage:
+        Usage::
+        
           %run [-n -i -e -G]
                [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
                ( -m mod | file ) [args]
@@ -371,14 +381,13 b' python-profiler package from non-free.""")'
         the program (put in sys.argv). Then, control returns to IPython's
         prompt.
 
-        This is similar to running at a system prompt:\\
-          $ python file args\\
+        This is similar to running at a system prompt ``python file args``,
         but with the advantage of giving you IPython's tracebacks, and of
         loading all variables into your interactive namespace for further use
         (unless -p is used, see below).
 
         The file is executed in a namespace initially consisting only of
-        __name__=='__main__' and sys.argv constructed as indicated. It thus
+        ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
         sees its environment as if it were being run as a stand-alone program
         (except for sharing global objects such as previously imported
         modules). But after execution, the IPython interactive namespace gets
@@ -390,33 +399,37 b' python-profiler package from non-free.""")'
         '*', '?', '[seq]' and '[!seq]' can be used.  Additionally,
         tilde '~' will be expanded into user's home directory.  Unlike
         real shells, quotation does not suppress expansions.  Use
-        *two* back slashes (e.g., '\\\\*') to suppress expansions.
+        *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
         To completely disable these expansions, you can use -G flag.
 
         Options:
 
-        -n: __name__ is NOT set to '__main__', but to the running file's name
-        without extension (as python does under import).  This allows running
-        scripts and reloading the definitions in them without calling code
-        protected by an ' if __name__ == "__main__" ' clause.
-
-        -i: run the file in IPython's namespace instead of an empty one. This
-        is useful if you are experimenting with code written in a text editor
-        which depends on variables defined interactively.
-
-        -e: ignore sys.exit() calls or SystemExit exceptions in the script
-        being run.  This is particularly useful if IPython is being used to
-        run unittests, which always exit with a sys.exit() call.  In such
-        cases you are interested in the output of the test results, not in
-        seeing a traceback of the unittest module.
-
-        -t: print timing information at the end of the run.  IPython will give
-        you an estimated CPU time consumption for your script, which under
-        Unix uses the resource module to avoid the wraparound problems of
-        time.clock().  Under Unix, an estimate of time spent on system tasks
-        is also given (for Windows platforms this is reported as 0.0).
-
-        If -t is given, an additional -N<N> option can be given, where <N>
+        -n
+          __name__ is NOT set to '__main__', but to the running file's name
+          without extension (as python does under import).  This allows running
+          scripts and reloading the definitions in them without calling code
+          protected by an ``if __name__ == "__main__"`` clause.
+
+        -i
+          run the file in IPython's namespace instead of an empty one. This
+          is useful if you are experimenting with code written in a text editor
+          which depends on variables defined interactively.
+
+        -e
+          ignore sys.exit() calls or SystemExit exceptions in the script
+          being run.  This is particularly useful if IPython is being used to
+          run unittests, which always exit with a sys.exit() call.  In such
+          cases you are interested in the output of the test results, not in
+          seeing a traceback of the unittest module.
+
+        -t
+          print timing information at the end of the run.  IPython will give
+          you an estimated CPU time consumption for your script, which under
+          Unix uses the resource module to avoid the wraparound problems of
+          time.clock().  Under Unix, an estimate of time spent on system tasks
+          is also given (for Windows platforms this is reported as 0.0).
+
+        If -t is given, an additional ``-N<N>`` option can be given, where <N>
         must be an integer indicating how many times you want the script to
         run.  The final timing report will include total and per run results.
 
@@ -424,74 +437,78 b' python-profiler package from non-free.""")'
 
             In [1]: run -t uniq_stable
 
-            IPython CPU timings (estimated):\\
-              User  :    0.19597 s.\\
-              System:        0.0 s.\\
+            IPython CPU timings (estimated):
+              User  :    0.19597 s.
+              System:        0.0 s.
 
             In [2]: run -t -N5 uniq_stable
 
-            IPython CPU timings (estimated):\\
-            Total runs performed: 5\\
-              Times :      Total       Per run\\
-              User  :   0.910862 s,  0.1821724 s.\\
+            IPython CPU timings (estimated):
+            Total runs performed: 5
+              Times :      Total       Per run
+              User  :   0.910862 s,  0.1821724 s.
               System:        0.0 s,        0.0 s.
 
-        -d: run your program under the control of pdb, the Python debugger.
-        This allows you to execute your program step by step, watch variables,
-        etc.  Internally, what IPython does is similar to calling:
+        -d
+          run your program under the control of pdb, the Python debugger.
+          This allows you to execute your program step by step, watch variables,
+          etc.  Internally, what IPython does is similar to calling::
 
-          pdb.run('execfile("YOURFILENAME")')
+              pdb.run('execfile("YOURFILENAME")')
 
-        with a breakpoint set on line 1 of your file.  You can change the line
-        number for this automatic breakpoint to be <N> by using the -bN option
-        (where N must be an integer).  For example::
+          with a breakpoint set on line 1 of your file.  You can change the line
+          number for this automatic breakpoint to be <N> by using the -bN option
+          (where N must be an integer). For example::
 
-          %run -d -b40 myscript
+              %run -d -b40 myscript
 
-        will set the first breakpoint at line 40 in myscript.py.  Note that
-        the first breakpoint must be set on a line which actually does
-        something (not a comment or docstring) for it to stop execution.
+          will set the first breakpoint at line 40 in myscript.py.  Note that
+          the first breakpoint must be set on a line which actually does
+          something (not a comment or docstring) for it to stop execution.
 
-        Or you can specify a breakpoint in a different file::
+          Or you can specify a breakpoint in a different file::
 
-          %run -d -b myotherfile.py:20 myscript
+              %run -d -b myotherfile.py:20 myscript
 
-        When the pdb debugger starts, you will see a (Pdb) prompt.  You must
-        first enter 'c' (without quotes) to start execution up to the first
-        breakpoint.
+          When the pdb debugger starts, you will see a (Pdb) prompt.  You must
+          first enter 'c' (without quotes) to start execution up to the first
+          breakpoint.
 
-        Entering 'help' gives information about the use of the debugger.  You
-        can easily see pdb's full documentation with "import pdb;pdb.help()"
-        at a prompt.
+          Entering 'help' gives information about the use of the debugger.  You
+          can easily see pdb's full documentation with "import pdb;pdb.help()"
+          at a prompt.
 
-        -p: run program under the control of the Python profiler module (which
-        prints a detailed report of execution times, function calls, etc).
+        -p
+          run program under the control of the Python profiler module (which
+          prints a detailed report of execution times, function calls, etc).
 
-        You can pass other options after -p which affect the behavior of the
-        profiler itself. See the docs for %prun for details.
+          You can pass other options after -p which affect the behavior of the
+          profiler itself. See the docs for %prun for details.
 
-        In this mode, the program's variables do NOT propagate back to the
-        IPython interactive namespace (because they remain in the namespace
-        where the profiler executes them).
+          In this mode, the program's variables do NOT propagate back to the
+          IPython interactive namespace (because they remain in the namespace
+          where the profiler executes them).
 
-        Internally this triggers a call to %prun, see its documentation for
-        details on the options available specifically for profiling.
+          Internally this triggers a call to %prun, see its documentation for
+          details on the options available specifically for profiling.
 
         There is one special usage for which the text above doesn't apply:
         if the filename ends with .ipy, the file is run as ipython script,
         just as if the commands were written on IPython prompt.
 
-        -m: specify module name to load instead of script path. Similar to
-        the -m option for the python interpreter. Use this option last if you
-        want to combine with other %run options. Unlike the python interpreter
-        only source modules are allowed no .pyc or .pyo files.
-        For example::
+        -m
+          specify module name to load instead of script path. Similar to
+          the -m option for the python interpreter. Use this option last if you
+          want to combine with other %run options. Unlike the python interpreter
+          only source modules are allowed no .pyc or .pyo files.
+          For example::
 
-            %run -m example
+              %run -m example
 
-        will run the example module.
+          will run the example module.
 
-        -G: disable shell-like glob expansion of arguments.
+        -G
+          disable shell-like glob expansion of arguments.
 
         """
 

IPython/core/magics/logging.py

@@ -42,34 +42,48 b' class LoggingMagics(Magics):'
         history up to that point and then continues logging.
 
         %logstart takes a second optional parameter: logging mode. This can be one
-        of (note that the modes are given unquoted):\\
-          append: well, that says it.\\
-          backup: rename (if exists) to name~ and start name.\\
-          global: single logfile in your home dir, appended to.\\
-          over  : overwrite existing log.\\
-          rotate: create rotating logs name.1~, name.2~, etc.
+        of (note that the modes are given unquoted):
+
+        append
+            Keep logging at the end of any existing file.
+
+        backup
+            Rename any existing file to name~ and start name.
+
+        global
+            Append to  a single logfile in your home directory.
+
+        over
+            Overwrite any existing log.
+
+        rotate
+            Create rotating logs: name.1~, name.2~, etc.
 
         Options:
 
-          -o: log also IPython's output.  In this mode, all commands which
-          generate an Out[NN] prompt are recorded to the logfile, right after
-          their corresponding input line.  The output lines are always
-          prepended with a '#[Out]# ' marker, so that the log remains valid
-          Python code.
+          -o
+            log also IPython's output. In this mode, all commands which
+            generate an Out[NN] prompt are recorded to the logfile, right after
+            their corresponding input line. The output lines are always
+            prepended with a '#[Out]# ' marker, so that the log remains valid
+            Python code.
 
           Since this marker is always the same, filtering only the output from
           a log is very easy, using for example a simple awk call::
 
             awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
 
-          -r: log 'raw' input.  Normally, IPython's logs contain the processed
-          input, so that user lines are logged in their final form, converted
-          into valid Python.  For example, %Exit is logged as
-          _ip.magic("Exit").  If the -r flag is given, all input is logged
-          exactly as typed, with no transformations applied.
-
-          -t: put timestamps before each input line logged (these are put in
-          comments)."""
+          -r
+            log 'raw' input.  Normally, IPython's logs contain the processed
+            input, so that user lines are logged in their final form, converted
+            into valid Python.  For example, %Exit is logged as
+            _ip.magic("Exit").  If the -r flag is given, all input is logged
+            exactly as typed, with no transformations applied.
+
+          -t
+            put timestamps before each input line logged (these are put in
+            comments).
+        """
 
         opts,par = self.parse_options(parameter_s,'ort')
         log_output = 'o' in opts

IPython/core/magics/namespace.py

@@ -354,10 +354,10 b' class NamespaceMagics(Magics):'
           - For {},[],(): their length.
 
           - For numpy arrays, a summary with shape, number of
-          elements, typecode and size in memory.
+            elements, typecode and size in memory.
 
           - Everything else: a string representation, snipping their middle if
-          too long.
+            too long.
 
         Examples
         --------

IPython/core/oinspect.py

@@ -156,8 +156,8 b' def getsource(obj,is_binary=False):'
     Optional inputs:
 
     - is_binary: whether the object is known to come from a binary source.
-    This implementation will skip returning any output for binary objects, but
-    custom extractors may know how to meaningfully process them."""
+      This implementation will skip returning any output for binary objects, but
+      custom extractors may know how to meaningfully process them."""
 
     if is_binary:
         return None
@@ -545,7 +545,7 b' class Inspector:'
         - formatter: special formatter for docstrings (see pdoc)
 
         - info: a structure with some information fields which may have been
-        precomputed already.
+          precomputed already.
 
         - detail_level: if set to 1, more information is given.
         """
@@ -609,7 +609,7 b' class Inspector:'
         - formatter: special formatter for docstrings (see pdoc)
 
         - info: a structure with some information fields which may have been
-        precomputed already.
+          precomputed already.
 
         - detail_level: if set to 1, more information is given.
         """
@@ -829,8 +829,8 b' class Inspector:'
         Arguments:
 
         - pattern: string containing shell-like wildcards to use in namespace
-        searches and optionally a type specification to narrow the search to
-        objects of that type.
+          searches and optionally a type specification to narrow the search to
+          objects of that type.
 
         - ns_table: dict of name->namespaces for search.
 
@@ -841,7 +841,7 b' class Inspector:'
           - ignore_case(False): make the search case-insensitive.
 
           - show_all(False): show all names, including those starting with
-          underscores.
+            underscores.
         """
         #print 'ps pattern:<%r>' % pattern # dbg
 

IPython/core/page.py

@@ -325,9 +325,11 b" def snip_print(str,width = 75,print_full = 0,header = ''):"
     """Print a string snipping the midsection to fit in width.
 
     print_full: mode control:
+    
       - 0: only snip long strings
       - 1: send to page() directly.
       - 2: snip long strings and ask for full length viewing with page()
+    
     Return 1 if snipping was necessary, 0 otherwise."""
 
     if print_full == 1:

IPython/core/ultratb.py

@@ -8,7 +8,8 b' 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
 text editor.
 
-Installation instructions for ColorTB:
+Installation instructions for ColorTB::
+
     import sys,ultratb
     sys.excepthook = ultratb.ColorTB()
 
@@ -21,7 +22,7 b' but kind of neat, and maybe useful for long-running programs that you believe'
 are bug-free.  If a crash *does* occur in that type of program you want details.
 Give it a shot--you'll love it or you'll hate it.
 
-Note:
+.. note::
 
   The Verbose mode prints the variables currently visible where the exception
   happened (shortening their strings if too long). This can potentially be
@@ -36,25 +37,28 b' Note:'
   Verbose).
 
 
-Installation instructions for ColorTB:
+Installation instructions for ColorTB::
+
     import sys,ultratb
     sys.excepthook = ultratb.VerboseTB()
 
 Note:  Much of the code in this module was lifted verbatim from the standard
 library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'.
 
-* Color schemes
+Color schemes
+-------------
+
 The colors are defined in the class TBTools through the use of the
 ColorSchemeTable class. Currently the following exist:
 
   - NoColor: allows all of this module to be used in any terminal (the color
-  escapes are just dummy blank strings).
+    escapes are just dummy blank strings).
 
   - Linux: is meant to look good in a terminal like the Linux console (black
-  or very dark background).
+    or very dark background).
 
   - LightBG: similar to Linux but swaps dark/light colors to be more readable
-  in light background terminals.
+    in light background terminals.
 
 You can implement other color schemes easily, the syntax is fairly
 self-explanatory. Please send back new schemes you develop to the author for
@@ -359,8 +363,8 b' class TBTools(object):'
         Valid values are:
 
         - None: the default, which means that IPython will dynamically resolve
-        to io.stdout.  This ensures compatibility with most tools, including
-        Windows (where plain stdout doesn't recognize ANSI escapes).
+          to io.stdout.  This ensures compatibility with most tools, including
+          Windows (where plain stdout doesn't recognize ANSI escapes).
 
         - Any object with 'write' and 'flush' attributes.
         """
@@ -974,9 +978,9 b' class VerboseTB(TBTools):'
         Keywords:
 
           - force(False): by default, this routine checks the instance call_pdb
-          flag and does not actually invoke the debugger if the flag is false.
-          The 'force' option forces the debugger to activate even if the flag
-          is false.
+            flag and does not actually invoke the debugger if the flag is false.
+            The 'force' option forces the debugger to activate even if the flag
+            is false.
 
         If the call_pdb flag is set, the pdb interactive debugger is
         invoked. In all cases, the self.tb reference to the current traceback

IPython/lib/demo.py

@@ -14,14 +14,14 b' The classes are (see their docstrings for further details):'
  - Demo: pure python demos
 
  - IPythonDemo: demos with input to be processed by IPython as if it had been
- typed interactively (so magics work, as well as any other special syntax you
- may have added via input prefilters).
+   typed interactively (so magics work, as well as any other special syntax you
+   may have added via input prefilters).
 
  - LineDemo: single-line version of the Demo class.  These demos are executed
- one line at a time, and require no markup.
+   one line at a time, and require no markup.
 
  - IPythonLineDemo: IPython version of the LineDemo class (the demo is
- executed a line at a time, but processed via IPython).
+   executed a line at a time, but processed via IPython).
 
  - ClearMixin: mixin to make Demo classes with less visual clutter.  It
    declares an empty marquee and a pre_cmd that clears the screen before each
@@ -214,18 +214,18 b' class Demo(object):'
         Optional inputs:
 
           - title: a string to use as the demo name.  Of most use when the demo
-          you are making comes from an object that has no filename, or if you
-          want an alternate denotation distinct from the filename.
+            you are making comes from an object that has no filename, or if you
+            want an alternate denotation distinct from the filename.
 
           - arg_str(''): a string of arguments, internally converted to a list
-          just like sys.argv, so the demo script can see a similar
-          environment.
+            just like sys.argv, so the demo script can see a similar
+            environment.
 
           - auto_all(None): global flag to run all blocks automatically without
-          confirmation.  This attribute overrides the block-level tags and
-          applies to the whole demo.  It is an attribute of the object, and
-          can be changed at runtime simply by reassigning it to a boolean
-          value.
+            confirmation.  This attribute overrides the block-level tags and
+            applies to the whole demo.  It is an attribute of the object, and
+            can be changed at runtime simply by reassigning it to a boolean
+            value.
           """
         if hasattr(src, "read"):
              # It seems to be a file or a file-like object

IPython/lib/irunner.py

@@ -93,9 +93,9 b' class InteractiveRunner(object):'
           - program: command to execute the given program.
 
           - prompts: a list of patterns to match as valid prompts, in the
-          format used by pexpect.  This basically means that it can be either
-          a string (to be compiled as a regular expression) or a list of such
-          (it must be a true list, as pexpect does type checks).
+            format used by pexpect.  This basically means that it can be either
+            a string (to be compiled as a regular expression) or a list of such
+            (it must be a true list, as pexpect does type checks).
 
           If more than one prompt is given, the first is treated as the main
           program prompt and the others as 'continuation' prompts, like
@@ -107,19 +107,19 b' class InteractiveRunner(object):'
         Optional inputs:
 
           - args(None): optional list of strings to pass as arguments to the
-          child program.
+            child program.
 
           - out(sys.stdout): if given, an output stream to be used when writing
-          output.  The only requirement is that it must have a .write() method.
+            output.  The only requirement is that it must have a .write() method.
 
         Public members not parameterized in the constructor:
 
           - delaybeforesend(0): Newer versions of pexpect have a delay before
-          sending each new input.  For our purposes here, it's typically best
-          to just set this to zero, but if you encounter reliability problems
-          or want an interactive run to pause briefly at each prompt, just
-          increase this value (it is measured in seconds).  Note that this
-          variable is not honored at all by older versions of pexpect.
+            sending each new input.  For our purposes here, it's typically best
+            to just set this to zero, but if you encounter reliability problems
+            or want an interactive run to pause briefly at each prompt, just
+            increase this value (it is measured in seconds).  Note that this
+            variable is not honored at all by older versions of pexpect.
         """
 
         self.program = program
@@ -154,7 +154,7 b' class InteractiveRunner(object):'
 
         Inputs:
 
-          -fname: name of the file to execute.
+          - fname: name of the file to execute.
 
         See the run_source docstring for the meaning of the optional
         arguments."""
@@ -173,15 +173,15 b' class InteractiveRunner(object):'
         Inputs:
 
           - source: a string of code to be executed, or an open file object we
-          can iterate over.
+            can iterate over.
 
         Optional inputs:
 
           - interact(False): if true, start to interact with the running
-          program at the end of the script.  Otherwise, just exit.
+            program at the end of the script.  Otherwise, just exit.
 
           - get_output(False): if true, capture the output of the child process
-          (filtering the input commands out) and return it as a string.
+            (filtering the input commands out) and return it as a string.
 
         Returns:
           A string containing the process output, but only if requested.

IPython/nbconvert/preprocessors/coalescestreams.py

@@ -19,7 +19,8 b' def cell_preprocessor(function):'
     Wrap a function to be executed on all cells of a notebook
     
     Wrapped Parameters
-    ----------
+    ------------------
+    
     cell : NotebookNode cell
         Notebook cell being processed
     resources : dictionary

IPython/utils/_process_win32.py

@@ -44,8 +44,8 b' class AvoidUNCPath(object):'
     change and None otherwise, so that users can apply the necessary adjustment
     to their system calls in the event of a change.
 
-    Example
-    -------
+    Examples
+    --------
     ::
         cmd = 'dir'
         with AvoidUNCPath() as path:

IPython/utils/_process_win32_controller.py

@@ -161,8 +161,8 b' class AvoidUNCPath(object):'
     change and None otherwise, so that users can apply the necessary adjustment
     to their system calls in the event of a change.
 
-    Example
-    -------
+    Examples
+    --------
     ::
         cmd = 'dir'
         with AvoidUNCPath() as path:

IPython/utils/capture.py

@@ -69,12 +69,12 b' class CapturedIO(object):'
 
     Each instance `c` has three attributes:
 
-        c.stdout : standard output as a string
-        c.stderr : standard error as a string
-        c.outputs: a list of rich display outputs
+    - ``c.stdout`` : standard output as a string
+    - ``c.stderr`` : standard error as a string
+    - ``c.outputs``: a list of rich display outputs
 
-    Additionally, there's a `c.show()` method which will print all of the
-    above in the same order, and can be invoked simply via `c()`.
+    Additionally, there's a ``c.show()`` method which will print all of the
+    above in the same order, and can be invoked simply via ``c()``.
     """
     
     def __init__(self, stdout, stderr, outputs=None):
@@ -105,8 +105,8 b' class CapturedIO(object):'
     def outputs(self):
         """A list of the captured rich display outputs, if any.
         
-        If you have a CapturedIO object `c`, these can be displayed in IPython
-        using:
+        If you have a CapturedIO object ``c``, these can be displayed in IPython
+        using::
 
             from IPython.display import display
             for o in c.outputs:

IPython/utils/contexts.py

@@ -27,8 +27,8 b' class preserve_keys(object):'
     which did not exist when entering the context manager will be
     deleted.
 
-    Example
-    -------
+    Examples
+    --------
 
     >>> d = {'a': 1, 'b': 2, 'c': 3}
     >>> with preserve_keys(d, 'b', 'c', 'd'):

IPython/utils/sysinfo.py

@@ -98,18 +98,20 b' def pkg_info(pkg_path):'
 def sys_info():
     """Return useful information about IPython and the system, as a string.
 
-    Example
-    -------
-    In [2]: print sys_info()
-    {'commit_hash': '144fdae',      # random
-     'commit_source': 'repository',
-     'ipython_path': '/home/fperez/usr/lib/python2.6/site-packages/IPython',
-     'ipython_version': '0.11.dev',
-     'os_name': 'posix',
-     'platform': 'Linux-2.6.35-22-generic-i686-with-Ubuntu-10.10-maverick',
-     'sys_executable': '/usr/bin/python',
-     'sys_platform': 'linux2',
-     'sys_version': '2.6.6 (r266:84292, Sep 15 2010, 15:52:39) \\n[GCC 4.4.5]'}
+    Examples
+    --------
+    ::
+    
+        In [2]: print sys_info()
+        {'commit_hash': '144fdae',      # random
+         'commit_source': 'repository',
+         'ipython_path': '/home/fperez/usr/lib/python2.6/site-packages/IPython',
+         'ipython_version': '0.11.dev',
+         'os_name': 'posix',
+         'platform': 'Linux-2.6.35-22-generic-i686-with-Ubuntu-10.10-maverick',
+         'sys_executable': '/usr/bin/python',
+         'sys_platform': 'linux2',
+         'sys_version': '2.6.6 (r266:84292, Sep 15 2010, 15:52:39) \\n[GCC 4.4.5]'}
    """
     p = os.path
     path = p.dirname(p.abspath(p.join(__file__, '..')))