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

Miscellaneous docs fixes

IPython/core/debugger.py

@@ -162,7 +162,7 b' class Tracer(object):'
 
 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 b''
-"""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 b' from IPython.core.profiledir import ProfileDir'
 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 b' class InteractiveShell(SingletonConfigurable):'
                                                                 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 b' class InteractiveShell(SingletonConfigurable):'
         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 b' class HistoryMagics(Magics):'
 
         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 b' 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 b' class TBTools(object):'
 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 b' 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 b' 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 b' class FileLink(object):'
                  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 b' 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 b' 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 b' 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 b' import locale'
 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 b' 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 b' class NotificationCenter(object):'
         ----------
         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 b' 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 b' 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 b' 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 b" if __name__ == '__main__':"
                                            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 b''
    :Release: |version|
    :Date: |today|
 
-.. include:: generated/gen.txt
+.. include:: generated/gen.rst

docs/source/config/extensions/storemagic.txt

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

docs/source/config/overview.txt

@@ -394,6 +394,8 b' 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 b" 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 b' 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 b' 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 b' For instance:'
     $> ipython --TerminalIPythonApp.display_banner=False
 
 Subcommands
-***********
+-----------
 
 
 Some IPython applications have **subcommands**. Subcommands are modeled after

docs/source/interactive/reference.txt

@@ -166,7 +166,7 b' An example (with automagic on) should clarify all this:'
     /home/fperez/ipython
 
 Defining your own magics
-~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++
 
 There are two main ways to define your own magic functions: from standalone
 functions and by inheriting from a base class provided by IPython:
@@ -933,8 +933,8 b' starting point for writing your own extensions.'
 Pasting of code starting with Python or IPython prompts
 -------------------------------------------------------
 
-IPython is smart enough to filter  out input prompts, be they plain Python ones
-(``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``).  You can
+IPython is smart enough to filter out input prompts, be they plain Python ones
+(``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``).  You can
 therefore copy and paste from existing interactive sessions without worry.
 
 The following is a 'screenshot' of how things work, copying an example from the

docs/source/whatsnew/version0.11.txt

@@ -113,7 +113,7 b' A quick summary of the major changes (see below for details):'
 
 * **Pasting of code with prompts**. IPython now intelligently strips out input
   prompts , be they plain Python ones (``>>>`` and ``...``) or IPython ones
-  (``In [N]:`` and `` ...:``).  More details :ref:`here <pasting_with_prompts>`.
+  (``In [N]:`` and ``...:``).  More details :ref:`here <pasting_with_prompts>`.
   
 
 Authors and support
@@ -681,7 +681,7 b' available.'
   exec_lines in the config file.
 
 
-.. _credits_011::
+.. _credits_011:
 
 Credits
 -------

docs/source/whatsnew/version0.12.txt

@@ -241,8 +241,8 b' few major ones merit special mention:'
   Windows (:ghissue:`737`).
 
 * Instances of classes defined interactively can now be pickled (:ghissue:`29`;
-:ghpull:`648`). Note that pickling saves a reference to the class definition,
-so unpickling the instances will only work where the class has been defined.
+  :ghpull:`648`). Note that pickling saves a reference to the class definition,
+  so unpickling the instances will only work where the class has been defined.
 
 
 Backwards incompatible changes
@@ -261,13 +261,13 b' Backwards incompatible changes'
   each channel.
 
 * Custom prompts are now configured using a new class,
-:class:`~IPython.core.prompts.PromptManager`, which has traits for
-:attr:`in_template`, :attr:`in2_template` (the ``...:`` continuation prompt),
-:attr:`out_template` and :attr:`rewrite_template`. This uses Python's string
-formatting system, so you can use ``{time}`` and ``{cwd}``, although we have
-preserved the abbreviations from previous versions, e.g. ``\#`` (prompt number)
-and ``\w`` (working directory). For the list of available fields, refer to the
-source of :file:`IPython/core/prompts.py`.
+  :class:`~IPython.core.prompts.PromptManager`, which has traits for
+  :attr:`in_template`, :attr:`in2_template` (the ``...:`` continuation prompt),
+  :attr:`out_template` and :attr:`rewrite_template`. This uses Python's string
+  formatting system, so you can use ``{time}`` and ``{cwd}``, although we have
+  preserved the abbreviations from previous versions, e.g. ``\#`` (prompt number)
+  and ``\w`` (working directory). For the list of available fields, refer to the
+  source of :file:`IPython/core/prompts.py`.
 
 * The class inheritance of the Launchers in
   :mod:`IPython.parallel.apps.launcher` used by ipcluster has changed, so that
@@ -309,7 +309,7 b' Development summary and credits'
 The previous version (IPython 0.11) was released on July 31 2011, so this
 release cycle was roughly 4 1/2 months long, we closed a total of 515 issues,
 257 pull requests and 258 regular issues (a :ref:`detailed list
-<issues_list_012>`_ is available).
+<issues_list_012>` is available).
 
 Many users and developers contributed code, features, bug reports and ideas to
 this release.  Please do not hesitate in contacting us if we've failed to

docs/sphinxext/apigen.py

@@ -378,18 +378,15 b' class ApiDocWriter(object):'
         modules = self.discover_modules()
         self.write_modules_api(modules,outdir)
 
-    def write_index(self, outdir, froot='gen', relative_to=None):
+    def write_index(self, outdir, path='gen.rst', relative_to=None):
         """Make a reST API index file from written files
 
         Parameters
         ----------
-        path : string
-            Filename to write index to
         outdir : string
             Directory to which to write generated index file
-        froot : string, optional
-            root (filename without extension) of filename to write to
-            Defaults to 'gen'.  We add ``self.rst_extension``.
+        path : string
+            Filename to write index to
         relative_to : string
             path to which written filenames are relative.  This
             component of the written file path will be removed from
@@ -399,7 +396,7 b' class ApiDocWriter(object):'
         if self.written_modules is None:
             raise ValueError('No modules written')
         # Get full filename path
-        path = os.path.join(outdir, froot+self.rst_extension)
+        path = os.path.join(outdir, path)
         # Path written into index is relative to rootpath
         if relative_to is not None:
             relpath = outdir.replace(relative_to + os.path.sep, '')