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

@@ -31,7 +31,7 b' 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
+  ``__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.

IPython/core/debugger.py

@@ -96,18 +96,23 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()
 
-        ... later in your code
+        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

IPython/core/interactiveshell.py

@@ -3036,7 +3036,8 b' class InteractiveShell(SingletonConfigurable):'
 
         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/magics/execution.py

@@ -102,7 +102,8 b' python-profiler package from non-free.""")'
 
         Options:
 
-        -l <limit>: you can place restrictions on what or how much of the
+        -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
@@ -114,14 +115,16 b' python-profiler package from non-free.""")'
           (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
+          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
+        -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
+        -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'.
 
@@ -136,7 +139,9 b' python-profiler package from non-free.""")'
         abbreviation is unambiguous.  The following are the keys currently
         defined:
 
+          ============  =====================
                 Valid Arg       Meaning
+          ============  =====================
                   "calls"      call count
                   "cumulative" cumulative time
                   "file"       file name
@@ -147,6 +152,7 b' python-profiler package from non-free.""")'
                   "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
@@ -159,18 +165,21 b' python-profiler package from non-free.""")'
         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
+        -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
+        -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.
+        -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
+        -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.
+          protected by an ``if __name__ == "__main__"`` clause.
 
-        -i: run the file in IPython's namespace instead of an empty one. This
+        -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
+        -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
+        -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>
+        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,21 +437,22 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.
+        -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:
+          etc.  Internally, what IPython does is similar to calling::
 
           pdb.run('execfile("YOURFILENAME")')
 
@@ -464,7 +478,8 b' python-profiler package from non-free.""")'
         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
+        -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
@@ -481,7 +496,8 b' python-profiler package from non-free.""")'
         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
+        -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.
@@ -491,7 +507,8 b' python-profiler package from non-free.""")'
 
         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,16 +42,27 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
+          -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
@@ -62,14 +73,17 b' class LoggingMagics(Magics):'
 
             awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
 
-          -r: log 'raw' input.  Normally, IPython's logs contain the processed
+          -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)."""
+          -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/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,14 +37,17 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:
 

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,8 +98,10 b' def pkg_info(pkg_path):'
 def sys_info():
     """Return useful information about IPython and the system, as a string.
 
-    Example
-    -------
+    Examples
+    --------
+    ::
+    
     In [2]: print sys_info()
     {'commit_hash': '144fdae',      # random
      'commit_source': 'repository',