From 666fdfa8056b87cba990dcd08457e50e28d7f2fc 2013-01-24 16:47:41 From: Thomas Kluyver Date: 2013-01-24 16:47:41 Subject: [PATCH] Miscellaneous docs fixes --- diff --git a/IPython/core/debugger.py b/IPython/core/debugger.py index 151b39e..d918945 100644 --- a/IPython/core/debugger.py +++ b/IPython/core/debugger.py @@ -162,7 +162,7 @@ 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): diff --git a/IPython/core/hooks.py b/IPython/core/hooks.py index d47e11e..959d0b8 100644 --- a/IPython/core/hooks.py +++ b/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 +` or a :ref:`startup script `. 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. """ #***************************************************************************** diff --git a/IPython/core/interactiveshell.py b/IPython/core/interactiveshell.py index 95b1ea3..ffc638f 100644 --- a/IPython/core/interactiveshell.py +++ b/IPython/core/interactiveshell.py @@ -1902,10 +1902,10 @@ class InteractiveShell(SingletonConfigurable): 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 +2828,11 @@ 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 diff --git a/IPython/core/magics/history.py b/IPython/core/magics/history.py index 63bb4fa..869d77b 100644 --- a/IPython/core/magics/history.py +++ b/IPython/core/magics/history.py @@ -105,12 +105,19 @@ 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 diff --git a/IPython/core/payloadpage.py b/IPython/core/payloadpage.py index b118ec3..39f57fa 100644 --- a/IPython/core/payloadpage.py +++ b/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. diff --git a/IPython/core/ultratb.py b/IPython/core/ultratb.py index 203c78b..6a74a40 100644 --- a/IPython/core/ultratb.py +++ b/IPython/core/ultratb.py @@ -420,9 +420,9 @@ 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 @@ 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, diff --git a/IPython/lib/display.py b/IPython/lib/display.py index c315c50..c762d4c 100644 --- a/IPython/lib/display.py +++ b/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 = "%s" @@ -77,13 +77,17 @@ class FileLink(object): result_html_prefix='', result_html_suffix='
'): """ - 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: '
'] + 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: '
'] """ if isdir(path): raise ValueError,\ diff --git a/IPython/lib/inputhook.py b/IPython/lib/inputhook.py index c2dd403..d3b8f67 100644 --- a/IPython/lib/inputhook.py +++ b/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 ------- diff --git a/IPython/testing/decorators.py b/IPython/testing/decorators.py index 83ef955..5d9edcb 100644 --- a/IPython/testing/decorators.py +++ b/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 diff --git a/IPython/testing/tools.py b/IPython/testing/tools.py index 2b47f55..0c5b346 100644 --- a/IPython/testing/tools.py +++ b/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)' diff --git a/IPython/utils/encoding.py b/IPython/utils/encoding.py index 470cf8c..cff1906 100644 --- a/IPython/utils/encoding.py +++ b/IPython/utils/encoding.py @@ -20,9 +20,9 @@ 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: diff --git a/IPython/utils/nested_context.py b/IPython/utils/nested_context.py index 118c4de..46cbafb 100644 --- a/IPython/utils/nested_context.py +++ b/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() diff --git a/IPython/utils/notification.py b/IPython/utils/notification.py index 42c54a0..506356c 100644 --- a/IPython/utils/notification.py +++ b/IPython/utils/notification.py @@ -119,7 +119,7 @@ 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. diff --git a/IPython/utils/text.py b/IPython/utils/text.py index 86d52a1..736c524 100644 --- a/IPython/utils/text.py +++ b/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) diff --git a/docs/autogen_api.py b/docs/autogen_api.py index ed22e1c..17066b9 100755 --- a/docs/autogen_api.py +++ b/docs/autogen_api.py @@ -57,7 +57,9 @@ 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) diff --git a/docs/source/api/index.txt b/docs/source/api/index.txt index d5c55f4..7b0bea3 100644 --- a/docs/source/api/index.txt +++ b/docs/source/api/index.txt @@ -9,4 +9,4 @@ :Release: |version| :Date: |today| -.. include:: generated/gen.txt +.. include:: generated/gen.rst diff --git a/docs/source/config/extensions/storemagic.txt b/docs/source/config/extensions/storemagic.txt index b860c7e..1698104 100644 --- a/docs/source/config/extensions/storemagic.txt +++ b/docs/source/config/extensions/storemagic.txt @@ -5,4 +5,4 @@ storemagic ========== .. automodule:: IPython.extensions.storemagic - :members: magic_store + :members: store diff --git a/docs/source/config/overview.txt b/docs/source/config/overview.txt index 759fe4b..1c9ac35 100644 --- a/docs/source/config/overview.txt +++ b/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 diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt index 25641cb..0e3682f 100644 --- a/docs/source/interactive/reference.txt +++ b/docs/source/interactive/reference.txt @@ -166,7 +166,7 @@ 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 @@ 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 diff --git a/docs/source/whatsnew/version0.11.txt b/docs/source/whatsnew/version0.11.txt index c9bda34..ee81279 100644 --- a/docs/source/whatsnew/version0.11.txt +++ b/docs/source/whatsnew/version0.11.txt @@ -113,7 +113,7 @@ 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 `. + (``In [N]:`` and ``...:``). More details :ref:`here `. Authors and support @@ -681,7 +681,7 @@ available. exec_lines in the config file. -.. _credits_011:: +.. _credits_011: Credits ------- diff --git a/docs/source/whatsnew/version0.12.txt b/docs/source/whatsnew/version0.12.txt index cfa48c8..bfd78f4 100644 --- a/docs/source/whatsnew/version0.12.txt +++ b/docs/source/whatsnew/version0.12.txt @@ -241,8 +241,8 @@ 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 @@ 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 @@ 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 -`_ is available). +` 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 diff --git a/docs/sphinxext/apigen.py b/docs/sphinxext/apigen.py index 9486e1e..e655adb 100644 --- a/docs/sphinxext/apigen.py +++ b/docs/sphinxext/apigen.py @@ -378,18 +378,15 @@ 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 @@ 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, '')