update config docs with recent changes

* various classes have changed, profiles are dirs not files, etc.
* also add documentation of new command-line format

docs/source/config/extensions.txt

@@ -46,7 +46,7 b' There are two ways you can tell IPython to use your extension:'
 To load an extension called :file:`myextension.py` add the following logic
 to your configuration file::
 
-    c.Global.extensions = [
+    c.InteractiveShellApp.extensions = [
         'myextension'
     ]
 

docs/source/config/ipython.txt

@@ -15,63 +15,74 b' can configure the application. A sample is provided in'
 :mod:`IPython.config.default.ipython_config`.  Simply copy this file to your
 :ref:`IPython directory <ipython_dir>` to start using it.
 
-Most configuration attributes that this file accepts are associated with
-classes that are subclasses of :class:`~IPython.core.component.Component`.
+Most configuration attributes that this file accepts are associated with classes
+that are subclasses of :class:`~IPython.config.configurable.Configurable`.  
 
-A few configuration attributes are not associated with a particular 
-:class:`~IPython.core.component.Component` subclass.  These are application
-wide configuration attributes and are stored in the ``Global`` 
-sub-configuration section.  We begin with a description of these 
-attributes.
+Applications themselves are Configurable as well, so we will start with some
+application-level config.
 
-Global configuration
-====================
+Application-level configuration
+===============================
 
 Assuming that your configuration file has the following at the top::
 
     c = get_config()
 
-the following attributes can be set in the ``Global`` section.
+the following attributes are set application-wide:
 
-:attr:`c.IPythonApp.display_banner`
+terminal IPython-only flags:
+
+:attr:`c.TerminalIPythonApp.display_banner`
     A boolean that determined if the banner is printer when :command:`ipython`
     is started.
 
-:attr:`c.IPythonApp.classic`
+:attr:`c.TerminalIPythonApp.classic`
     A boolean that determines if IPython starts in "classic" mode.  In this
     mode, the prompts and everything mimic that of the normal :command:`python`
     shell
 
-:attr:`c.IPythonApp.nosep`
+:attr:`c.TerminalIPythonApp.nosep`
     A boolean that determines if there should be no blank lines between
     prompts.
 
-:attr:`c.IPythonApp.log_level`
+:attr:`c.Application.log_level`
     An integer that sets the detail of the logging level during the startup
     of :command:`ipython`.  The default is 30 and the possible values are
     (0, 10, 20, 30, 40, 50).  Higher is quieter and lower is more verbose.
+    This can also be set by the name of the logging level, e.g. INFO=20,
+    WARN=30.
+
+Some options, such as extensions and startup code, can be set for any
+application that starts an
+:class:`~IPython.core.interactiveshell.InteractiveShell`. These apps are
+subclasses of :class:`~IPython.core.shellapp.InteractiveShellApp`. Since
+subclasses inherit configuration, setting a trait of
+:attr:`c.InteractiveShellApp` will affect all IPython applications, but if you
+want terminal IPython and the QtConsole to have different values, you can set
+them via :attr:`c.TerminalIPythonApp` and :attr:`c.IPKernelApp` respectively.
+
 
-:attr:`c.IPythonApp.extensions`
+:attr:`c.InteractiveShellApp.extensions`
     A list of strings, each of which is an importable IPython extension. An
     IPython extension is a regular Python module or package that has a
     :func:`load_ipython_extension(ip)` method. This method gets called when
     the extension is loaded with the currently running
-    :class:`~IPython.core.iplib.InteractiveShell` as its only argument. You
-    can put your extensions anywhere they can be imported but we add the
-    :file:`extensions` subdirectory of the ipython directory to ``sys.path``
-    during extension loading, so you can put them there as well. Extensions
-    are not executed in the user's interactive namespace and they must be pure
-    Python code. Extensions are the recommended way of customizing
+    :class:`~IPython.core.interactiveshell.InteractiveShell` as its only
+    argument. You can put your extensions anywhere they can be imported but we
+    add the :file:`extensions` subdirectory of the ipython directory to
+    ``sys.path`` during extension loading, so you can put them there as well.
+    Extensions are not executed in the user's interactive namespace and they
+    must be pure Python code. Extensions are the recommended way of customizing
     :command:`ipython`. Extensions can provide an
     :func:`unload_ipython_extension` that will be called when the extension is
     unloaded.
 
-:attr:`c.IPythonApp.exec_lines`
+:attr:`c.InteractiveShellApp.exec_lines`
     A list of strings, each of which is Python code that is run in the user's
     namespace after IPython start. These lines can contain full IPython syntax
     with magics, etc.
 
-:attr:`c.IPythonApp.exec_files`
+:attr:`c.InteractiveShellApp.exec_files`
     A list of strings, each of which is the full pathname of a ``.py`` or
     ``.ipy`` file that will be executed as IPython starts. These files are run
     in IPython in the user's namespace. Files with a ``.py`` extension need to
@@ -85,7 +96,7 b' Classes that can be configured'
 The following classes can also be configured in the configuration file for
 :command:`ipython`:
 
-* :class:`~IPython.core.iplib.InteractiveShell`
+* :class:`~IPython.core.interactiveshell.InteractiveShell`
 
 * :class:`~IPython.core.prefilter.PrefilterManager`
 
@@ -105,16 +116,16 b' attributes::'
     # sample ipython_config.py
     c = get_config()
 
-    c.IPythonApp.display_banner = True
-    c.IPythonApp.log_level = 20
-    c.IPythonApp.extensions = [
+    c.IPythonTerminalApp.display_banner = True
+    c.InteractiveShellApp.log_level = 20
+    c.InteractiveShellApp.extensions = [
         'myextension'
     ]
-    c.IPythonApp.exec_lines = [
+    c.InteractiveShellApp.exec_lines = [
         'import numpy',
         'import scipy'
     ]
-    c.IPythonApp.exec_files = [
+    c.InteractiveShellApp.exec_files = [
         'mycode.py',
         'fancy.ipy'
     ]

docs/source/config/overview.txt

@@ -18,8 +18,8 b' met our requirements.'
     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 user's how to configure
-IPython to their liking.  Developer's who want to know more about how they
+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>`
 
@@ -37,15 +37,19 b' Configuration object: :class:`~IPython.config.loader.Config`'
     are smart. They know how to merge themselves with other configuration
     objects and they automatically create sub-configuration objects.
 
-Application: :class:`~IPython.core.application.Application`
+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 a *single* configuration file and command line options
+    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.
 
 Component: :class:`~IPython.config.configurable.Configurable`
     A configurable is a regular Python class that serves as a base class for
@@ -64,6 +68,25 b' Component: :class:`~IPython.config.configurable.Configurable`'
     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
@@ -106,7 +129,7 b' subclass::'
     from IPython.utils.traitlets import Int, Float, Str, Bool
     
     class MyClass(Configurable):
-        name = Str('defaultname', config=True)
+        name = Unicode(u'defaultname', config=True)
         ranking = Int(0, config=True)
         value = Float(99.0)
         # The rest of the class implementation would go here..
@@ -197,6 +220,15 b' 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
 =====================================
 
@@ -241,9 +273,10 b' This class hierarchy and configuration file accomplishes the following:'
 Configuration file location
 ===========================
 
-So where should you put your configuration files?  By default, all IPython
-applications look in the so called "IPython directory".  The location of
-this directory is determined by the following algorithm:
+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.
 
@@ -263,26 +296,41 b' 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 what filename to use for the 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`.  This value can be overriden by the ``config_file``
-command line flag.  A sample :file:`ipython_config.py` file can be found
-in :mod:`IPython.config.default.ipython_config.py`.  Simple copy it to your
-IPython directory to begin using it.
+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 simply a configuration file that follows a simple naming
-convention and can be loaded using a simplified syntax.  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 file for each of these purposes.
+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:
 
@@ -290,18 +338,107 b" Let's start by showing how a profile is used:"
 
     $ ipython profile=sympy
 
-This tells the :command:`ipython` command line program to get its
-configuration from the "sympy" profile. The search path for profiles is the
-same as that of regular configuration files. The only difference is that
-profiles are named in a special way. In the case above, the "sympy" profile
-would need to have the name :file:`ipython_config_sympy.py`.
+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
+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'
+
+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'
+    # is equivalent to
+    $> 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
+    # and 
+    $> ipython --pylab
+    # is equivalent to
+    $> 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
+
+and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
+stop, engines).
+
+.. code-block:: bash
+
+    $> ipcluster start profile=myprofile n=4
+
 
-The general pattern is this: simply add ``<profilename>`` to the end of the
-normal configuration file name. Then load the profile by adding 
-``profile=<profilename>`` to your command line options.
+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``.
 
-IPython ships with some sample profiles in :mod:`IPython.config.profile`.
-Simply copy these to your IPython directory to begin using them.
 
 Design requirements
 ===================

docs/source/development/index.txt

@@ -23,4 +23,3 b" IPython developer's guide"
    ipgraph.txt
    ipython_qt.txt
    ipythonzmq.txt
-   parallelzmq.txt