Update more examples of command line args in the docs, and make a few minor formatting corrections.

docs/source/config/extensions.txt

@@ -1,61 +1,61 b''
 .. _extensions_overview:
 
 ==================
 IPython extensions
 ==================
 
 Configuration files are just the first level of customization that IPython
 supports. The next level is that of extensions. An IPython extension is an
 importable Python module that has a a few special function. By defining these
 functions, users can customize IPython by accessing the actual runtime objects
 of IPython.  Here is a sample extension::
 
     # myextension.py
 
     def load_ipython_extension(ipython):
         # The ``ipython`` argument is the currently active 
         # :class:`InteractiveShell` instance that can be used in any way.
         # This allows you do to things like register new magics, plugins or
         # aliases.
 
     def unload_ipython_extension(ipython):
         # If you want your extension to be unloadable, put that logic here.
 
 This :func:`load_ipython_extension` function is called after your extension is
 imported and the currently active :class:`InteractiveShell` instance is passed
 as the only argument. You can do anything you want with IPython at that point.
 
 The :func:`load_ipython_extension` will be called again is you load or reload
 the extension again. It is up to the extension author to add code to manage
 that.
 
 You can put your extension modules anywhere you want, as long as they can be
 imported by Python's standard import mechanism. However, to make it easy to
 write extensions, you can also put your extensions in
 ``os.path.join(self.ipython_dir, 'extensions')``. This directory is added to
 ``sys.path`` automatically.
 
 Using extensions
 ================
 
 There are two ways you can tell IPython to use your extension:
 
 1. Listing it in a configuration file.
 2. Using the ``%load_ext`` magic function.
 
 To load an extension called :file:`myextension.py` add the following logic
 to your configuration file::
 
     c.InteractiveShellApp.extensions = [
         'myextension'
     ]
 
-To load that same extension at runtime, use the ``%load_ext`` magic::
+To load that same extension at runtime, use the ``%load_ext`` magic:
 
 .. sourcecode:: ipython
 
     In [1]: %load_ext myextension
 
 To summarize, in conjunction with configuration files and profiles, IPython
 extensions give you complete and flexible control over your IPython
 setup.

docs/source/config/overview.txt

@@ -1,479 +1,479 b''
 .. _config_overview:
 
 ============================================
 Overview of the IPython configuration system
 ============================================
 
 This section describes the IPython configuration system. Starting with version
 0.11, IPython has a completely new configuration system that is quite
 different from the older :file:`ipythonrc` or :file:`ipy_user_conf.py`
 approaches. The new configuration system was designed from scratch to address
 the particular configuration needs of IPython. While there are many
 other excellent configuration systems out there, we found that none of them
 met our requirements.
 
 .. warning::
 
     If you are upgrading to version 0.11 of IPython, you will need to migrate
     your old :file:`ipythonrc` or :file:`ipy_user_conf.py` configuration files
     to the new system.  Read on for information on how to do this.
 
 The discussion that follows is focused on teaching users how to configure
 IPython to their liking.  Developers who want to know more about how they
 can enable their objects to take advantage of the configuration system
 should consult our :ref:`developer guide <developer_guide>`
 
 The main concepts
 =================
 
 There are a number of abstractions that the IPython configuration system uses.
 Each of these abstractions is represented by a Python class.
 
 Configuration object: :class:`~IPython.config.loader.Config`
     A configuration object is a simple dictionary-like class that holds
     configuration attributes and sub-configuration objects. These classes
     support dotted attribute style access (``Foo.bar``) in addition to the
     regular dictionary style access (``Foo['bar']``). Configuration objects
     are smart. They know how to merge themselves with other configuration
     objects and they automatically create sub-configuration objects.
 
 Application: :class:`~IPython.config.application.Application`
     An application is a process that does a specific job. The most obvious
     application is the :command:`ipython` command line program. Each
     application reads *one or more* configuration files and a single set of
     command line options
     and then produces a master configuration object for the application. This
     configuration object is then passed to the configurable objects that the
     application creates. These configurable objects implement the actual logic
     of the application and know how to configure themselves given the
     configuration object.
     
     Applications always have a `log` attribute that is a configured Logger.
     This allows centralized logging configuration per-application.
 
 Configurable: :class:`~IPython.config.configurable.Configurable`
     A configurable is a regular Python class that serves as a base class for
     all main classes in an application. The
     :class:`~IPython.config.configurable.Configurable` base class is
     lightweight and only does one things.
 
     This :class:`~IPython.config.configurable.Configurable` is a subclass
     of :class:`~IPython.utils.traitlets.HasTraits` that knows how to configure
     itself. Class level traits with the metadata ``config=True`` become
     values that can be configured from the command line and configuration
     files.
     
     Developers create :class:`~IPython.config.configurable.Configurable`
     subclasses that implement all of the logic in the application. Each of
     these subclasses has its own configuration information that controls how
     instances are created.
 
 Singletons: :class:`~IPython.config.configurable.SingletonConfigurable`
     Any object for which there is a single canonical instance. These are
     just like Configurables, except they have a class method 
     :meth:`~IPython.config.configurable.SingletonConfigurable.instance`,
     that returns the current active instance (or creates one if it
     does not exist).  Examples of singletons include
     :class:`~IPython.config.application.Application`s and
     :class:`~IPython.core.interactiveshell.InteractiveShell`.  This lets
     objects easily connect to the current running Application without passing
     objects around everywhere.  For instance, to get the current running 
     Application instance, simply do: ``app = Application.instance()``.
 
 
 .. note::
 
     Singletons are not strictly enforced - you can have many instances
     of a given singleton class, but the :meth:`instance` method will always
     return the same one.
 
 Having described these main concepts, we can now state the main idea in our
 configuration system: *"configuration" allows the default values of class
 attributes to be controlled on a class by class basis*. Thus all instances of
 a given class are configured in the same way. Furthermore, if two instances
 need to be configured differently, they need to be instances of two different
 classes. While this model may seem a bit restrictive, we have found that it
 expresses most things that need to be configured extremely well. However, it
 is possible to create two instances of the same class that have different
 trait values. This is done by overriding the configuration.
 
 Now, we show what our configuration objects and files look like.
 
 Configuration objects and files
 ===============================
 
 A configuration file is simply a pure Python file that sets the attributes
 of a global, pre-created configuration object.  This configuration object is a 
 :class:`~IPython.config.loader.Config` instance.  While in a configuration
 file, to get a reference to this object, simply call the :func:`get_config`
 function.  We inject this function into the global namespace that the 
 configuration file is executed in.
 
 Here is an example of a super simple configuration file that does nothing::
 
     c = get_config()
 
 Once you get a reference to the configuration object, you simply set
 attributes on it.  All you have to know is:
 
 * The name of each attribute.
 * The type of each attribute.
 
 The answers to these two questions are provided by the various
 :class:`~IPython.config.configurable.Configurable` subclasses that an
 application uses. Let's look at how this would work for a simple configurable
 subclass::
 
     # Sample configurable:
     from IPython.config.configurable import Configurable
     from IPython.utils.traitlets import Int, Float, Unicode, Bool
     
     class MyClass(Configurable):
         name = Unicode(u'defaultname', config=True)
         ranking = Int(0, config=True)
         value = Float(99.0)
         # The rest of the class implementation would go here..
 
 In this example, we see that :class:`MyClass` has three attributes, two
 of whom (``name``, ``ranking``) can be configured.  All of the attributes
 are given types and default values.  If a :class:`MyClass` is instantiated,
 but not configured, these default values will be used.  But let's see how
 to configure this class in a configuration file::
 
     # Sample config file
     c = get_config()
     
     c.MyClass.name = 'coolname'
     c.MyClass.ranking = 10
 
 After this configuration file is loaded, the values set in it will override
 the class defaults anytime a :class:`MyClass` is created.  Furthermore,
 these attributes will be type checked and validated anytime they are set.
 This type checking is handled by the :mod:`IPython.utils.traitlets` module,
 which provides the :class:`Unicode`, :class:`Int` and :class:`Float` types.
 In addition to these traitlets, the :mod:`IPython.utils.traitlets` provides
 traitlets for a number of other types.
 
 .. note::
 
     Underneath the hood, the :class:`Configurable` base class is a subclass of
     :class:`IPython.utils.traitlets.HasTraits`. The
     :mod:`IPython.utils.traitlets` module is a lightweight version of
     :mod:`enthought.traits`. Our implementation is a pure Python subset
     (mostly API compatible) of :mod:`enthought.traits` that does not have any
     of the automatic GUI generation capabilities. Our plan is to achieve 100%
     API compatibility to enable the actual :mod:`enthought.traits` to
     eventually be used instead. Currently, we cannot use
     :mod:`enthought.traits` as we are committed to the core of IPython being
     pure Python.
 
 It should be very clear at this point what the naming convention is for 
 configuration attributes::
 
     c.ClassName.attribute_name = attribute_value
 
 Here, ``ClassName`` is the name of the class whose configuration attribute you
 want to set, ``attribute_name`` is the name of the attribute you want to set
 and ``attribute_value`` the the value you want it to have. The ``ClassName``
 attribute of ``c`` is not the actual class, but instead is another
 :class:`~IPython.config.loader.Config` instance.
 
 .. note::
 
     The careful reader may wonder how the ``ClassName`` (``MyClass`` in
     the above example) attribute of the configuration object ``c`` gets
     created. These attributes are created on the fly by the
     :class:`~IPython.config.loader.Config` instance, using a simple naming
     convention. Any attribute of a :class:`~IPython.config.loader.Config`
     instance whose name begins with an uppercase character is assumed to be a
     sub-configuration and a new empty :class:`~IPython.config.loader.Config`
     instance is dynamically created for that attribute. This allows deeply
     hierarchical information created easily (``c.Foo.Bar.value``) on the fly.
 
 Configuration files inheritance
 ===============================
 
 Let's say you want to have different configuration files for various purposes.
 Our configuration system makes it easy for one configuration file to inherit
 the information in another configuration file. The :func:`load_subconfig`
 command can be used in a configuration file for this purpose. Here is a simple
 example that loads all of the values from the file :file:`base_config.py`::
 
     # base_config.py
     c = get_config()
     c.MyClass.name = 'coolname'
     c.MyClass.ranking = 100
 
 into the configuration file :file:`main_config.py`::
 
     # main_config.py
     c = get_config()
     
     # Load everything from base_config.py
     load_subconfig('base_config.py')
     
     # Now override one of the values
     c.MyClass.name = 'bettername'
 
 In a situation like this the :func:`load_subconfig` makes sure that the
 search path for sub-configuration files is inherited from that of the parent.
 Thus, you can typically put the two in the same directory and everything will
 just work.
 
 You can also load configuration files by profile, for instance:
 
 .. sourcecode:: python
 
     load_subconfig('ipython_config.py', profile='default')
 
 to inherit your default configuration as a starting point.
 
 
 Class based configuration inheritance
 =====================================
 
 There is another aspect of configuration where inheritance comes into play.
 Sometimes, your classes will have an inheritance hierarchy that you want
 to be reflected in the configuration system.  Here is a simple example::
 
     from IPython.config.configurable import Configurable
     from IPython.utils.traitlets import Int, Float, Unicode, Bool
     
     class Foo(Configurable):
         name = Unicode(u'fooname', config=True)
         value = Float(100.0, config=True)
     
     class Bar(Foo):
         name = Unicode(u'barname', config=True)
         othervalue = Int(0, config=True)
 
 Now, we can create a configuration file to configure instances of :class:`Foo`
 and :class:`Bar`::
 
     # config file
     c = get_config()
     
     c.Foo.name = u'bestname'
     c.Bar.othervalue = 10
 
 This class hierarchy and configuration file accomplishes the following:
 
 * The default value for :attr:`Foo.name` and :attr:`Bar.name` will be
   'bestname'.  Because :class:`Bar` is a :class:`Foo` subclass it also
   picks up the configuration information for :class:`Foo`.
 * The default value for :attr:`Foo.value` and :attr:`Bar.value` will be
   ``100.0``, which is the value specified as the class default.
 * The default value for :attr:`Bar.othervalue` will be 10 as set in the
   configuration file.  Because :class:`Foo` is the parent of :class:`Bar`
   it doesn't know anything about the :attr:`othervalue` attribute.
 
 
 .. _ipython_dir:
 
 Configuration file location
 ===========================
 
 So where should you put your configuration files? IPython uses "profiles" for
 configuration, and by default, all profiles will be stored in the so called
 "IPython directory". The location of this directory is determined by the
 following algorithm:
 
 * If the ``ipython_dir`` command line flag is given, its value is used.
 
 * If not, the value returned by :func:`IPython.utils.path.get_ipython_dir`
   is used. This function will first look at the :envvar:`IPYTHON_DIR`
   environment variable and then default to a platform-specific default.
 
 On posix systems (Linux, Unix, etc.), IPython respects the ``$XDG_CONFIG_HOME``
 part of the `XDG Base Directory`_ specification. If ``$XDG_CONFIG_HOME`` is
 defined and exists ( ``XDG_CONFIG_HOME`` has a default interpretation of
 :file:`$HOME/.config`), then IPython's config directory will be located in
 :file:`$XDG_CONFIG_HOME/ipython`.  If users still have an IPython directory
 in :file:`$HOME/.ipython`, then that will be used. in preference to the 
 system default.
 
 For most users, the default value will simply be something like 
 :file:`$HOME/.config/ipython` on Linux, or :file:`$HOME/.ipython`
 elsewhere.
 
 Once the location of the IPython directory has been determined, you need to know
 which profile you are using. For users with a single configuration, this will
 simply be 'default', and will be located in 
 :file:`<IPYTHON_DIR>/profile_default`.
 
 The next thing you need to know is what to call your configuration file. The
 basic idea is that each application has its own default configuration filename.
 The default named used by the :command:`ipython` command line program is
 :file:`ipython_config.py`, and *all* IPython applications will use this file.
 Other applications, such as the parallel :command:`ipcluster` scripts or the
 QtConsole will load their own config files *after* :file:`ipython_config.py`. To
 load a particular configuration file instead of the default, the name can be
 overridden by the ``config_file`` command line flag.
 
 To generate the default configuration files, do::
 
     $> ipython profile create
 
 and you will have a default :file:`ipython_config.py` in your IPython directory
 under :file:`profile_default`. If you want the default config files for the
 :mod:`IPython.parallel` applications, add ``--parallel`` to the end of the
 command-line args.
 
 .. _Profiles:
 
 Profiles
 ========
 
 A profile is a directory containing configuration and runtime files, such as
 logs, connection info for the parallel apps, and your IPython command history.
 
 The idea is that users often want to maintain a set of configuration files for
 different purposes: one for doing numerical computing with NumPy and SciPy and
 another for doing symbolic computing with SymPy. Profiles make it easy to keep a
 separate configuration files, logs, and histories for each of these purposes.
 
 Let's start by showing how a profile is used:
 
 .. code-block:: bash
 
-    $ ipython profile=sympy
+    $ ipython --profile=sympy
 
 This tells the :command:`ipython` command line program to get its configuration
 from the "sympy" profile. The file names for various profiles do not change. The
 only difference is that profiles are named in a special way. In the case above,
 the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHON_DIR>/profile_sympy`.
 
 The general pattern is this: simply create a new profile with:
 
 .. code-block:: bash
 
     ipython profile create <name>
 
 which adds a directory called ``profile_<name>`` to your IPython directory. Then
-you can load this profile by adding ``profile=<name>`` to your command line
+you can load this profile by adding ``--profile=<name>`` to your command line
 options. Profiles are supported by all IPython applications.
 
 IPython ships with some sample profiles in :file:`IPython/config/profile`. If
 you create profiles with the name of one of our shipped profiles, these config
 files will be copied over instead of starting with the automatically generated
 config files.
 
 .. _commandline:
 
 Command-line arguments
 ======================
 
 IPython exposes *all* configurable options on the command-line. The command-line
 arguments are generated from the Configurable traits of the classes associated
 with a given Application.  Configuring IPython from the command-line may look
 very similar to an IPython config file
 
 IPython applications use a parser called
 :class:`~IPython.config.loader.KeyValueLoader` to load values into a Config
 object.  Values are assigned in much the same way as in a config file:
 
 .. code-block:: bash
 
-    $> ipython InteractiveShell.use_readline=False BaseIPythonApplication.profile='myprofile'
+    $> ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'
 
 Is the same as adding:
 
 .. sourcecode:: python
 
     c.InteractiveShell.use_readline=False
     c.BaseIPythonApplication.profile='myprofile'
 
 to your config file. Key/Value arguments *always* take a value, separated by '='
 and no spaces.
 
 Aliases
 -------
 
 For convenience, applications have a mapping of commonly
 used traits, so you don't have to specify the whole class name. For these **aliases**, the class need not be specified:
 
 .. code-block:: bash
 
-    $> ipython profile='myprofile'
+    $> ipython --profile='myprofile'
     # is equivalent to
-    $> ipython BaseIPythonApplication.profile='myprofile'
+    $> ipython --BaseIPythonApplication.profile='myprofile'
 
 Flags
 -----
 
 Applications can also be passed **flags**. Flags are options that take no
 arguments, and are always prefixed with ``--``. They are simply wrappers for
 setting one or more configurables with predefined values, often True/False.
 
 For instance:
 
 .. code-block:: bash
 
     $> ipcontroller --debug
     # is equivalent to
-    $> ipcontroller Application.log_level=DEBUG
+    $> ipcontroller --Application.log_level=DEBUG
     # and 
     $> ipython --pylab
     # is equivalent to
-    $> ipython pylab=auto
+    $> ipython --pylab=auto
 
 Subcommands
 -----------
 
 
 Some IPython applications have **subcommands**. Subcommands are modeled after
 :command:`git`, and are called with the form :command:`command subcommand
 [...args]`.  Currently, the QtConsole is a subcommand of terminal IPython:
 
 .. code-block:: bash
 
-    $> ipython qtconsole profile=myprofile
+    $> ipython qtconsole --profile=myprofile
 
 and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
 stop, engines).
 
 .. code-block:: bash
 
-    $> ipcluster start profile=myprofile n=4
+    $> ipcluster start --profile=myprofile --n=4
 
 
 To see a list of the available aliases, flags, and subcommands for an IPython application, simply pass ``-h`` or ``--help``.  And to see the full list of configurable options (*very* long), pass ``--help-all``.
 
 
 Design requirements
 ===================
 
 Here are the main requirements we wanted our configuration system to have:
 
 * Support for hierarchical configuration information.
 
 * Full integration with command line option parsers.  Often, you want to read
   a configuration file, but then override some of the values with command line
   options.  Our configuration system automates this process and allows each
   command line option to be linked to a particular attribute in the 
   configuration hierarchy that it will override.
 
 * Configuration files that are themselves valid Python code. This accomplishes
   many things. First, it becomes possible to put logic in your configuration
   files that sets attributes based on your operating system, network setup,
   Python version, etc. Second, Python has a super simple syntax for accessing
   hierarchical data structures, namely regular attribute access
   (``Foo.Bar.Bam.name``). Third, using Python makes it easy for users to
   import configuration attributes from one configuration file to another.
   Fourth, even though Python is dynamically typed, it does have types that can
   be checked at runtime. Thus, a ``1`` in a config file is the integer '1',
   while a ``'1'`` is a string.
 
 * A fully automated method for getting the configuration information to the
   classes that need it at runtime. Writing code that walks a configuration
   hierarchy to extract a particular attribute is painful. When you have
   complex configuration information with hundreds of attributes, this makes
   you want to cry.
 
 * Type checking and validation that doesn't require the entire configuration
   hierarchy to be specified statically before runtime. Python is a very
   dynamic language and you don't always know everything that needs to be
   configured when a program starts.
 
 
 .. _`XDG Base Directory`: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

docs/source/development/testing.txt

@@ -1,391 +1,393 b''
 .. _testing:
 
 ==========================================
  Testing IPython for users and developers
 ==========================================
 
 Overview
 ========
 
 It is extremely important that all code contributed to IPython has tests.
 Tests should be written as unittests, doctests or other entities that the
 IPython test system can detect.  See below for more details on this.
 
 Each subpackage in IPython should have its own :file:`tests` directory that
 contains all of the tests for that subpackage. All of the files in the
 :file:`tests` directory should have the word "tests" in them to enable
 the testing framework to find them.
 
 In docstrings, examples (either using IPython prompts like ``In [1]:`` or
 'classic' python ``>>>`` ones) can and should be included.  The testing system
 will detect them as doctests and will run them; it offers control to skip parts
 or all of a specific doctest if the example is meant to be informative but
 shows non-reproducible information (like filesystem data).
 
 If a subpackage has any dependencies beyond the Python standard library, the
 tests for that subpackage should be skipped if the dependencies are not found.
 This is very important so users don't get tests failing simply because they
 don't have dependencies.
 
 The testing system we use is a hybrid of nose_ and Twisted's trial_ test runner.
 We use both because nose detects more things than Twisted and allows for more
 flexible (and lighter-weight) ways of writing tests; in particular we've
 developed a nose plugin that allows us to paste verbatim IPython sessions and
 test them as doctests, which is extremely important for us.  But the parts of
 IPython that depend on Twisted must be tested using trial, because only trial
 manages the Twisted reactor correctly.
 
 .. _nose: http://code.google.com/p/python-nose
 .. _trial: http://twistedmatrix.com/trac/wiki/TwistedTrial
 
 
 For the impatient: running the tests
 ====================================
 
 You can run IPython from the source download directory without even installing
 it system-wide or having configure anything, by typing at the terminal:
 
 .. code-block:: bash
 
    python ipython.py
 
 In order to run the test suite, you must at least be able to import IPython,
 even if you haven't fully installed the user-facing scripts yet (common in a
 development environment).  You can then run the tests with:
 
 .. code-block:: bash
 
   python -c "import IPython; IPython.test()"
 
 Once you have installed IPython either via a full install or using:
 
 .. code-block:: bash
 
   python setup.py develop
 
 you will have available a system-wide script called :file:`iptest` that runs
 the full test suite.  You can then run the suite with:
 
 .. code-block:: bash
 
    iptest  [args]
 
 
 Regardless of how you run things, you should eventually see something like:
 
 .. code-block:: bash
 
    **********************************************************************
    Test suite completed for system with the following information:
    {'commit_hash': '144fdae',
     '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]'}
 
    Tools and libraries available at test time:
       curses foolscap gobject gtk pexpect twisted wx wx.aui zope.interface
 
    Ran 9 test groups in 67.213s
 
    Status:
    OK
 
 
 If not, there will be a message indicating which test group failed and how to
 rerun that group individually.  For example, this tests the
 :mod:`IPython.utils` subpackage, the :option:`-v` option shows progress
 indicators:
 
 .. code-block:: bash
 
    $ iptest -v IPython.utils
    ..........................SS..SSS............................S.S...
    .........................................................
    ----------------------------------------------------------------------
    Ran 125 tests in 0.119s
 
    OK (SKIP=7)
 
 
 Because the IPython test machinery is based on nose, you can use all nose
 options and syntax, typing ``iptest -h`` shows all available options.  For
 example, this lets you run the specific test :func:`test_rehashx` inside the
 :mod:`test_magic` module:
 
 .. code-block:: bash
 
    $ iptest -vv IPython.core.tests.test_magic:test_rehashx
    IPython.core.tests.test_magic.test_rehashx(True,) ... ok
    IPython.core.tests.test_magic.test_rehashx(True,) ... ok
 
    ----------------------------------------------------------------------
    Ran 2 tests in 0.100s
 
    OK
 
 When developing, the :option:`--pdb` and :option:`--pdb-failures` of nose are
 particularly useful, these drop you into an interactive pdb session at the
 point of the error or failure respectively.
 
 To run Twisted-using tests, use the :command:`trial` command on a per file or
 package basis:
 
 .. code-block:: bash
 
     trial IPython.kernel
 
 .. note::
 
    The system information summary printed above is accessible from the top
    level package.  If you encounter a problem with IPython, it's useful to
    include this information when reporting on the mailing list; use::
 
        from IPython import sys_info
        print sys_info()
 
    and include the resulting information in your query.
 
 For developers: writing tests
 =============================
 
 By now IPython has a reasonable test suite, so the best way to see what's
 available is to look at the :file:`tests` directory in most subpackages.  But
 here are a few pointers to make the process easier.
 
 
 Main tools: :mod:`IPython.testing`
 ----------------------------------
 
 The :mod:`IPython.testing` package is where all of the machinery to test
 IPython (rather than the tests for its various parts) lives.  In particular,
 the :mod:`iptest` module in there has all the smarts to control the test
 process.  In there, the :func:`make_exclude` function is used to build a
 blacklist of exclusions, these are modules that do not get even imported for
 tests.  This is important so that things that would fail to even import because
 of missing dependencies don't give errors to end users, as we stated above.
 
 The :mod:`decorators` module contains a lot of useful decorators, especially
 useful to mark individual tests that should be skipped under certain conditions
 (rather than blacklisting the package altogether because of a missing major
 dependency).
 
 Our nose plugin for doctests
 ----------------------------
 
 The :mod:`plugin` subpackage in testing contains a nose plugin called
 :mod:`ipdoctest` that teaches nose about IPython syntax, so you can write
 doctests with IPython prompts.  You can also mark doctest output with ``#
 random`` for the output corresponding to a single input to be ignored (stronger
 than using ellipsis and useful to keep it as an example).  If you want the
 entire docstring to be executed but none of the output from any input to be
 checked, you can use the ``# all-random`` marker.  The
 :mod:`IPython.testing.plugin.dtexample` module contains examples of how to use
 these; for reference here is how to use ``# random``::
 
     def ranfunc():
 	"""A function with some random output.
 
 	   Normal examples are verified as usual:
 	   >>> 1+3
 	   4
 
 	   But if you put '# random' in the output, it is ignored:
 	   >>> 1+3
 	   junk goes here...  # random
 
 	   >>> 1+2
 	   again,  anything goes #random
 	   if multiline, the random mark is only needed once.
 
 	   >>> 1+2
 	   You can also put the random marker at the end:
 	   # random
 
 	   >>> 1+2
 	   # random
 	   .. or at the beginning.
 
 	   More correct input is properly verified:
 	   >>> ranfunc()
 	   'ranfunc'
 	"""
 	return 'ranfunc'
 
 and an example of ``# all-random``::
 	
     def random_all():
 	"""A function where we ignore the output of ALL examples.
 
 	Examples:
 
 	  # all-random
 
 	  This mark tells the testing machinery that all subsequent examples
 	  should be treated as random (ignoring their output).  They are still
 	  executed, so if a they raise an error, it will be detected as such,
 	  but their output is completely ignored.
 
 	  >>> 1+3
 	  junk goes here...
 
 	  >>> 1+3
 	  klasdfj;
 
 	In [8]: print 'hello'
 	world  # random
 
 	In [9]: iprand()
 	Out[9]: 'iprand'
 	"""
 	return 'iprand'
 
 
 When writing docstrings, you can use the ``@skip_doctest`` decorator to
 indicate that a docstring should *not* be treated as a doctest at all.  The
 difference between ``# all-random`` and ``@skip_doctest`` is that the former
 executes the example but ignores output, while the latter doesn't execute any
 code.  ``@skip_doctest`` should be used for docstrings whose examples are
 purely informational.
 
 If a given docstring fails under certain conditions but otherwise is a good
 doctest, you can use code like the following, that relies on the 'null'
 decorator to leave the docstring intact where it works as a test::
 
   # The docstring for full_path doctests differently on win32 (different path
   # separator) so just skip the doctest there, and use a null decorator
   # elsewhere:
   
   doctest_deco = dec.skip_doctest if sys.platform == 'win32' else dec.null_deco
 
   @doctest_deco
   def full_path(startPath,files):
       """Make full paths for all the listed files, based on startPath..."""
 
       # function body follows...
 
 With our nose plugin that understands IPython syntax, an extremely effective
 way to write tests is to simply copy and paste an interactive session into a
 docstring.  You can writing this type of test, where your docstring is meant
 *only* as a test, by prefixing the function name with ``doctest_`` and leaving
 its body *absolutely empty* other than the docstring.  In
 :mod:`IPython.core.tests.test_magic` you can find several examples of this, but
 for completeness sake, your code should look like this (a simple case)::
 
     def doctest_time():
 	"""
 	In [10]: %time None
 	CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
 	Wall time: 0.00 s
 	"""
 	
 This function is only analyzed for its docstring but it is not considered a
 separate test, which is why its body should be empty.
 
 
 Parametric tests done right
 ---------------------------
 
 If you need to run multiple tests inside the same standalone function or method
 of a :class:`unittest.TestCase` subclass, IPython provides the ``parametric``
 decorator for this purpose.  This is superior to how test generators work in
 nose, because IPython's keeps intact your stack, which makes debugging vastly
 easier.  For example, these are some parametric tests both in class form and as
 a standalone function (choose in each situation the style that best fits the
 problem at hand, since both work)::
 
   from IPython.testing import decorators as dec
 
   def is_smaller(i,j):
       assert i<j,"%s !< %s" % (i,j)
 
   class Tester(ParametricTestCase):
 
       def test_parametric(self):
 	  yield is_smaller(3, 4)
 	  x, y = 1, 2
 	  yield is_smaller(x, y)
 
   @dec.parametric
   def test_par_standalone():
       yield is_smaller(3, 4)
       x, y = 1, 2
       yield is_smaller(x, y)
       
 
 Writing tests for Twisted-using code
 ------------------------------------
       
 Tests of Twisted [Twisted]_ using code should be written by subclassing the
 ``TestCase`` class that comes with ``twisted.trial.unittest``. Furthermore, all
 :class:`Deferred` instances that are created in the test must be properly
 chained and the final one *must* be the return value of the test method.
 
 .. note::
   
   The best place to see how to use the testing tools, are the tests for these
   tools themselves, which live in :mod:`IPython.testing.tests`.
   
     
 Design requirements
 ===================
 
 This section is a set of notes on the key points of the IPython testing needs,
 that were used when writing the system and should be kept for reference as it
 eveolves.
 
 Testing IPython in full requires modifications to the default behavior of nose
 and doctest, because the IPython prompt is not recognized to determine Python
 input, and because IPython admits user input that is not valid Python (things
 like ``%magics`` and ``!system commands``.
 
 We basically need to be able to test the following types of code:
 
 1. Pure Python files containing normal tests.  These are not a problem, since
    Nose will pick them up as long as they conform to the (flexible) conventions
    used by nose to recognize tests.
 
-2. Python files containing doctests.  Here, we have two possibilities:
+2. Python files containing doctests. Here, we have two possibilities:
+   
    - The prompts are the usual ``>>>`` and the input is pure Python.
    - The prompts are of the form ``In [1]:`` and the input can contain extended
      IPython expressions.
 
    In the first case, Nose will recognize the doctests as long as it is called
    with the ``--with-doctest`` flag.  But the second case will likely require
    modifications or the writing of a new doctest plugin for Nose that is
    IPython-aware.
 
 3. ReStructuredText files that contain code blocks.  For this type of file, we
    have three distinct possibilities for the code blocks:
+   
    - They use ``>>>`` prompts.
    - They use ``In [1]:`` prompts.
    - They are standalone blocks of pure Python code without any prompts.
 
    The first two cases are similar to the situation #2 above, except that in
    this case the doctests must be extracted from input code blocks using
    docutils instead of from the Python docstrings.
 
    In the third case, we must have a convention for distinguishing code blocks
    that are meant for execution from others that may be snippets of shell code
    or other examples not meant to be run.  One possibility is to assume that
    all indented code blocks are meant for execution, but to have a special
    docutils directive for input that should not be executed.
 
    For those code blocks that we will execute, the convention used will simply
    be that they get called and are considered successful if they run to
    completion without raising errors.  This is similar to what Nose does for
    standalone test functions, and by putting asserts or other forms of
    exception-raising statements it becomes possible to have literate examples
    that double as lightweight tests.
 
 4. Extension modules with doctests in function and method docstrings.
    Currently Nose simply can't find these docstrings correctly, because the
    underlying doctest DocTestFinder object fails there.  Similarly to #2 above,
    the docstrings could have either pure python or IPython prompts.
 
 Of these, only 3-c (reST with standalone code blocks) is not implemented at
 this point.