Merge pull request #2841 from takluyver/misc-doc-fixes

Miscellaneous docs fixes

IPython/core/debugger.py

@@ -162,7 +162,7 @@ def __call__(self):
 
 def decorate_fn_with_doc(new_fn, old_fn, additional_text=""):
     """Make new_fn have old_fn's doc string. This is particularly useful
-    for the do_... commands that hook into the help system.
+    for the ``do_...`` commands that hook into the help system.
     Adapted from from a comp.lang.python posting
     by Duncan Booth."""
     def wrapper(*args, **kw):

IPython/core/hooks.py

@@ -1,37 +1,31 @@
-"""hooks for IPython.
+"""Hooks for IPython.
 
 In Python, it is possible to overwrite any method of any object if you really
-want to.  But IPython exposes a few 'hooks', methods which are _designed_ to
+want to.  But IPython exposes a few 'hooks', methods which are *designed* to
 be overwritten by users for customization purposes.  This module defines the
 default versions of all such hooks, which get used by IPython if not
 overridden by the user.
 
-hooks are simple functions, but they should be declared with 'self' as their
+Hooks are simple functions, but they should be declared with ``self`` as their
 first argument, because when activated they are registered into IPython as
-instance methods.  The self argument will be the IPython running instance
+instance methods. The self argument will be the IPython running instance
 itself, so hooks have full access to the entire IPython object.
 
-If you wish to define a new hook and activate it, you need to put the
-necessary code into a python file which can be either imported or execfile()'d
-from within your profile's ipython_config.py configuration.
+If you wish to define a new hook and activate it, you can make an :doc:`extension
+</config/extensions/index>` or a :ref:`startup script <startup_files>`. For
+example, you could use a startup file like this::
 
-For example, suppose that you have a module called 'myiphooks' in your
-PYTHONPATH, which contains the following definition:
+    import os
 
-import os
-from IPython.core import ipapi
-ip = ipapi.get()
-
-def calljed(self,filename, linenum):
-    "My editor hook calls the jed editor directly."
-    print "Calling my own editor, jed ..."
-    if os.system('jed +%d %s' % (linenum,filename)) != 0:
-        raise TryNext()
+    def calljed(self,filename, linenum):
+        "My editor hook calls the jed editor directly."
+        print "Calling my own editor, jed ..."
+        if os.system('jed +%d %s' % (linenum,filename)) != 0:
+            raise TryNext()
 
-ip.set_hook('editor', calljed)
+    def load_ipython_extension(ip):
+        ip.set_hook('editor', calljed)
 
-You can then enable the functionality by doing 'import myiphooks'
-somewhere in your configuration files or ipython command line.
 """
 
 #*****************************************************************************

IPython/core/interactiveshell.py

@@ -59,6 +59,7 @@
 from IPython.core.pylabtools import pylab_activate
 from IPython.core.prompts import PromptManager
 from IPython.lib.latextools import LaTeXTool
+from IPython.testing.skipdoctest import skip_doctest
 from IPython.utils import PyColorize
 from IPython.utils import io
 from IPython.utils import py3compat
@@ -1897,15 +1898,16 @@ def refill_readline_hist(self):
                                                                 stdin_encoding))
                 last_cell = cell
 
+    @skip_doctest
     def set_next_input(self, s):
         """ Sets the 'default' input string for the next command line.
 
         Requires readline.
 
-        Example:
+        Example::
 
-        [D:\ipython]|1> _ip.set_next_input("Hello Word")
-        [D:\ipython]|2> Hello Word_  # cursor is here
+            In [1]: _ip.set_next_input("Hello Word")
+            In [2]: Hello Word_  # cursor is here
         """
         self.rl_next_input = py3compat.cast_bytes_py2(s)
 
@@ -2828,12 +2830,11 @@ def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
         This turns on support for matplotlib, preloads into the interactive
         namespace all of numpy and pylab, and configures IPython to correctly
         interact with the GUI event loop.  The GUI backend to be used can be
-        optionally selected with the optional :param:`gui` argument.
+        optionally selected with the optional ``gui`` argument.
 
         Parameters
         ----------
         gui : optional, string
-
           If given, dictates the choice of matplotlib GUI backend to use
           (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
           'gtk', 'wx' or 'inline'), otherwise we use the default chosen by

IPython/core/magics/history.py

@@ -105,12 +105,19 @@ def history(self, parameter_s = ''):
 
         By default, all input history from the current session is displayed.
         Ranges of history can be indicated using the syntax:
-        4      : Line 4, current session
-        4-6    : Lines 4-6, current session
-        243/1-5: Lines 1-5, session 243
-        ~2/7   : Line 7, session 2 before current
-        ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
-                    of 6 sessions ago.
+        
+        ``4``
+            Line 4, current session
+        ``4-6``
+            Lines 4-6, current session
+        ``243/1-5``
+            Lines 1-5, session 243
+        ``~2/7``
+            Line 7, session 2 before current
+        ``~8/1-~6/5``
+            From the first line of 8 sessions ago, to the fifth line of 6
+            sessions ago.
+        
         Multiple ranges can be entered, separated by spaces
 
         The same syntax is used by %macro, %save, %edit, %rerun

IPython/core/payloadpage.py

@@ -57,8 +57,8 @@ def page(strng, start=0, screen_lines=0, pager_cmd=None,
       converted to HTML with docutils.  Note that if docutils is not found,
       this option is silently ignored.
 
-    Note
-    ----
+    Notes
+    -----
 
     Only one of the ``html`` and ``auto_html`` options can be given, not
     both.

IPython/core/ultratb.py

@@ -420,9 +420,9 @@ def structured_traceback(self, etype, evalue, tb, tb_offset=None,
 class ListTB(TBTools):
     """Print traceback information from a traceback list, with optional color.
 
-    Calling: requires 3 arguments:
-      (etype, evalue, elist)
-    as would be obtained by:
+    Calling requires 3 arguments: (etype, evalue, elist)
+    as would be obtained by::
+    
       etype, evalue, tb = sys.exc_info()
       if tb:
         elist = traceback.extract_tb(tb)
@@ -1130,13 +1130,13 @@ class AutoFormattedTB(FormattedTB):
 
     It will find out about exceptions by itself.
 
-    A brief example:
+    A brief example::
 
-    AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
-    try:
-      ...
-    except:
-      AutoTB()  # or AutoTB(out=logfile) where logfile is an open file object
+        AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
+        try:
+          ...
+        except:
+          AutoTB()  # or AutoTB(out=logfile) where logfile is an open file object
     """
 
     def __call__(self,etype=None,evalue=None,etb=None,

IPython/lib/display.py

@@ -59,14 +59,14 @@ class FileLink(object):
 
     e.g. to embed a link that was generated in the IPython notebook as my/data.txt
 
-    you would do:
+    you would do::
 
-    local_file = FileLink("my/data.txt")
-    display(local_file)
+        local_file = FileLink("my/data.txt")
+        display(local_file)
     
-    or in the HTML notebook, just
+    or in the HTML notebook, just::
     
-    FileLink("my/data.txt")
+        FileLink("my/data.txt")
     """
 
     html_link_str = "<a href='%s' target='_blank'>%s</a>"
@@ -77,13 +77,17 @@ def __init__(self,
                  result_html_prefix='',
                  result_html_suffix='<br>'):
         """
-            path : path to the file or directory that should be formatted
-            directory_prefix : prefix to be prepended to all files to form a
-             working link [default: 'files']
-            result_html_prefix : text to append to beginning to link
-             [default: none]
-            result_html_suffix : text to append at the end of link
-             [default: '<br>']
+        Parameters
+        ----------
+        path : str
+            path to the file or directory that should be formatted
+        directory_prefix : str
+            prefix to be prepended to all files to form a working link [default:
+            'files']
+        result_html_prefix : str
+            text to append to beginning to link [default: none]
+        result_html_suffix : str 
+            text to append at the end of link [default: '<br>']
         """
         if isdir(path):
             raise ValueError,\

IPython/lib/inputhook.py

@@ -500,7 +500,7 @@ def enable_gui(gui=None, app=None):
       For toolkits that have the concept of a global app, you can supply an
       existing one.  If not given, the toolkit will be probed for one, and if
       none is found, a new one will be created.  Note that GTK does not have
-      this concept, and passing an app if `gui`=="GTK" will raise an error.
+      this concept, and passing an app if ``gui=="GTK"`` will raise an error.
 
     Returns
     -------

IPython/testing/decorators.py

@@ -183,10 +183,10 @@ def skipif(skip_condition, msg=None):
     Parameters
     ----------
     skip_condition : bool or callable.
-    Flag to determine whether to skip test.  If the condition is a
-    callable, it is used at runtime to dynamically make the decision.  This
-    is useful for tests that may require costly imports, to delay the cost
-    until the test suite is actually executed.
+        Flag to determine whether to skip test.  If the condition is a
+        callable, it is used at runtime to dynamically make the decision.  This
+        is useful for tests that may require costly imports, to delay the cost
+        until the test suite is actually executed.
     msg : string
         Message to give on raising a SkipTest exception
 

IPython/testing/tools.py

@@ -97,6 +97,7 @@ def parse_test_output(txt):
     txt : str
       Text output of a test run, assumed to contain a line of one of the
       following forms::
+      
         'FAILED (errors=1)'
         'FAILED (failures=1)'
         'FAILED (errors=1, failures=1)'

IPython/utils/encoding.py

@@ -20,9 +20,9 @@
 def get_stream_enc(stream, default=None):
     """Return the given stream's encoding or a default.
 
-    There are cases where sys.std* might not actually be a stream, so
+    There are cases where ``sys.std*`` might not actually be a stream, so
     check for the encoding attribute prior to returning it, and return
-    a default if it doesn't exist or evaluates as False. `default'
+    a default if it doesn't exist or evaluates as False. ``default``
     is None if not provided.
     """
     if not hasattr(stream, 'encoding') or not stream.encoding:

IPython/utils/nested_context.py

@@ -17,7 +17,7 @@ def nested(*managers):
 
    The one advantage of this function over the multiple manager form of the
    with statement is that argument unpacking allows it to be
-   used with a variable number of context managers as follows:
+   used with a variable number of context managers as follows::
 
       with nested(*managers):
           do_something()

IPython/utils/notification.py

@@ -119,7 +119,7 @@ def add_observer(self, callback, ntype, sender):
         ----------
         callback : callable
             The callable that will be called by :meth:`post_notification`
-            as ``callback(ntype, sender, *args, **kwargs)
+            as ``callback(ntype, sender, *args, **kwargs)``
         ntype : hashable
             The notification type. If None, all notifications from sender
             will be posted.

IPython/utils/text.py

@@ -770,8 +770,8 @@ def _get_or_default(mylist, i, default=None):
 def compute_item_matrix(items, empty=None, *args, **kwargs) :
     """Returns a nested list, and info to columnize items
 
-    Parameters :
-    ------------
+    Parameters
+    ----------
 
     items :
         list of strings to columize
@@ -782,8 +782,8 @@ def compute_item_matrix(items, empty=None, *args, **kwargs) :
     displaywidth : int (default=80)
         The width of the area onto wich the columns should enter
 
-    Returns :
-    ---------
+    Returns
+    -------
 
     Returns a tuple of (strings_matrix, dict_info)
 
@@ -802,8 +802,8 @@ def compute_item_matrix(items, empty=None, *args, **kwargs) :
         columns_width   : list of with of each columns
         optimal_separator_width : best separator width between columns
 
-    Exemple :
-    ---------
+    Examples
+    --------
 
     In [1]: l = ['aaa','b','cc','d','eeeee','f','g','h','i','j','k','l']
        ...: compute_item_matrix(l,displaywidth=12)

docs/autogen_api.py

@@ -57,7 +57,9 @@
                                            r'\.testing\.mkdoctests']
     # Now, generate the outputs
     docwriter.write_api_docs(outdir)
-    docwriter.write_index(outdir, 'gen',
+    # Write index with .rst extension - we can include it, but Sphinx won't try
+    # to compile it
+    docwriter.write_index(outdir, 'gen.rst',
                           relative_to = pjoin('source','api')
                           )
     print '%d files written' % len(docwriter.written_modules)

docs/source/api/index.txt

@@ -9,4 +9,4 @@
    :Release: |version|
    :Date: |today|
 
-.. include:: generated/gen.txt
+.. include:: generated/gen.rst

docs/source/config/extensions/storemagic.txt

@@ -5,4 +5,4 @@ storemagic
 ==========
 
 .. automodule:: IPython.extensions.storemagic
-   :members: magic_store
+   :members: store

docs/source/config/overview.txt

@@ -394,6 +394,8 @@ convenience function :func:`IPython.utils.path.get_security_file`, which will re
 the absolute path to a security file from its filename and [optionally] profile
 name.
 
+.. _startup_files:
+
 Startup Files
 -------------
 
@@ -440,7 +442,7 @@ to your config file. Key/Value arguments *always* take a value, separated by '='
 and no spaces.
 
 Common Arguments
-****************
+----------------
 
 Since the strictness and verbosity of the KVLoader above are not ideal for everyday
 use, common arguments can be specified as flags_ or aliases_.
@@ -454,7 +456,7 @@ that are single characters, in which case they can be specified with a single ``
     $> ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
 
 Aliases
--------
+*******
 
 For convenience, applications have a mapping of commonly used traits, so you don't have
 to specify the whole class name:
@@ -468,7 +470,7 @@ to specify the whole class name:
     $> ipython --BaseIPythonApplication.profile='myprofile'
 
 Flags
------
+*****
 
 Applications can also be passed **flags**. Flags are options that take no
 arguments. They are simply wrappers for
@@ -491,7 +493,7 @@ For instance:
     $> ipython --TerminalIPythonApp.display_banner=False
 
 Subcommands
-***********
+-----------
 
 
 Some IPython applications have **subcommands**. Subcommands are modeled after