Merge pull request #4492 from takluyver/docs-refresh

Configuration docs refresh

- Moved the technical details of the config system into the development directory.
- Added a new 'intro' document describing how to use the config system, without the technical info.
- Autogenerate lists of config options for the main components (this doesn't yet include the parallel machinery).
- Condense and tidy up other config docs, removing outdated information.

docs/autogen_config.py

@@ -0,0 +1,74 b''
+from IPython.utils.text import indent, wrap_paragraphs
+
+from IPython.terminal.ipapp import TerminalIPythonApp
+from IPython.kernel.zmq.kernelapp import IPKernelApp
+from IPython.html.notebookapp import NotebookApp
+from IPython.qt.console.qtconsoleapp import IPythonQtConsoleApp
+
+def document_config_options(classes):
+    lines = []
+    for cls in classes:
+        classname = cls.__name__
+        for k, trait in sorted(cls.class_traits(config=True).items()):
+            ttype = trait.__class__.__name__
+
+            termline = classname + '.' + trait.name
+
+            # Choices or type
+            if 'Enum' in ttype:
+                # include Enum choices
+                termline += ' : ' + '|'.join(repr(x) for x in trait.values)
+            else:
+                termline += ' : ' + ttype
+            lines.append(termline)
+
+            # Default value
+            try:
+                dv = trait.get_default_value()
+                dvr = repr(dv)
+            except Exception:
+                dvr = dv = None # ignore defaults we can't construct
+            if (dv is not None) and (dvr is not None):
+                if len(dvr) > 64:
+                    dvr = dvr[:61]+'...'
+                # Double up backslashes, so they get to the rendered docs
+                dvr = dvr.replace('\\n', '\\\\n')
+                lines.append('    Default: ' + dvr)
+                lines.append('')
+
+            help = trait.get_metadata('help')
+            if help is not None:
+                help = '\n\n'.join(wrap_paragraphs(help, 76))
+                lines.append(indent(help, 4))
+            else:
+                lines.append('    No description')
+
+            lines.append('')
+    return '\n'.join(lines)
+
+kernel_classes = IPKernelApp().classes
+
+def write_doc(filename, title, classes, preamble=None):
+    configdoc = document_config_options(classes)
+    with open('source/config/options/%s.rst' % filename, 'w') as f:
+        f.write(title + '\n')
+        f.write(('=' * len(title)) + '\n')
+        f.write('\n')
+        if preamble is not None:
+            f.write(preamble + '\n\n')
+        f.write(configdoc)
+
+if __name__ == '__main__':
+    write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp().classes)
+    write_doc('kernel', 'IPython kernel options', kernel_classes,
+              preamble="These options can be used in :file:`ipython_notebook_config.py` "
+              "or in :file:`ipython_qtconsole_config.py`")
+    nbclasses = set(NotebookApp().classes) - set(kernel_classes)
+    write_doc('notebook', 'IPython notebook options', nbclasses,
+              preamble="Any of the :doc:`kernel` can also be used.")
+    qtclasses = set(IPythonQtConsoleApp().classes) - set(kernel_classes)
+    write_doc('qtconsole', 'IPython Qt console options', qtclasses,
+              preamble="Any of the :doc:`kernel` can also be used.")
+
+    with open('source/config/options/generated', 'w'):
+        pass
  No newline at end of file

docs/source/config/details.rst

@@ -0,0 +1,234 b''
+=======================
+Specific config details
+=======================
+
+Prompts
+=======
+
+In the terminal, the format of the input and output prompts can be
+customised. This does not currently affect other frontends.
+
+The following codes in the prompt string will be substituted into the
+prompt string:
+
+======  ===================================  =====================================================
+Short   Long                                 Notes
+======  ===================================  =====================================================
+%n,\\#  {color.number}{count}{color.prompt}  history counter with bolding
+\\N     {count}                              history counter without bolding
+\\D     {dots}                               series of dots the same width as the history counter
+\\T     {time}                               current time
+\\w     {cwd}                                current working directory
+\\W     {cwd_last}                           basename of CWD
+\\Xn    {cwd_x[n]}                           Show the last n terms of the CWD. n=0 means show all.
+\\Yn    {cwd_y[n]}                           Like \Xn, but show '~' for $HOME
+\\h                                          hostname, up to the first '.'
+\\H                                          full hostname
+\\u                                          username (from the $USER environment variable)
+\\v                                          IPython version
+\\$                                          root symbol ("$" for normal user or "#" for root)
+``\\``                                       escaped '\\'
+\\n                                          newline
+\\r                                          carriage return
+n/a     {color.<Name>}                       set terminal colour - see below for list of names
+======  ===================================  =====================================================
+
+Available colour names are: Black, BlinkBlack, BlinkBlue, BlinkCyan,
+BlinkGreen, BlinkLightGray, BlinkPurple, BlinkRed, BlinkYellow, Blue,
+Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, LightGreen,
+LightPurple, LightRed, Purple, Red, White, Yellow. The selected colour
+scheme also defines the names *prompt* and *number*. Finally, the name
+*normal* resets the terminal to its default colour.
+
+So, this config::
+
+     c.PromptManager.in_template = "{color.LightGreen}{time}{color.Yellow} \u{color.normal}>>>"
+
+will produce input prompts with the time in light green, your username
+in yellow, and a ``>>>`` prompt in the default terminal colour.
+
+
+.. _termcolour:
+
+Terminal Colors
+===============
+
+The default IPython configuration has most bells and whistles turned on
+(they're pretty safe). But there's one that may cause problems on some
+systems: the use of color on screen for displaying information. This is
+very useful, since IPython can show prompts and exception tracebacks
+with various colors, display syntax-highlighted source code, and in
+general make it easier to visually parse information.
+
+The following terminals seem to handle the color sequences fine:
+
+    * Linux main text console, KDE Konsole, Gnome Terminal, E-term,
+      rxvt, xterm.
+    * CDE terminal (tested under Solaris). This one boldfaces light colors.
+    * (X)Emacs buffers. See the :ref:`emacs` section for more details on
+      using IPython with (X)Emacs.
+    * A Windows (XP/2k) command prompt with pyreadline_.
+    * A Windows (XP/2k) CygWin shell. Although some users have reported
+      problems; it is not clear whether there is an issue for everyone
+      or only under specific configurations. If you have full color
+      support under cygwin, please post to the IPython mailing list so
+      this issue can be resolved for all users.
+
+.. _pyreadline: https://code.launchpad.net/pyreadline
+      
+These have shown problems:
+
+    * Windows command prompt in WinXP/2k logged into a Linux machine via
+      telnet or ssh.
+    * Windows native command prompt in WinXP/2k, without Gary Bishop's
+      extensions. Once Gary's readline library is installed, the normal
+      WinXP/2k command prompt works perfectly.
+
+Currently the following color schemes are available:
+
+    * NoColor: uses no color escapes at all (all escapes are empty '' ''
+      strings). This 'scheme' is thus fully safe to use in any terminal.
+    * Linux: works well in Linux console type environments: dark
+      background with light fonts. It uses bright colors for
+      information, so it is difficult to read if you have a light
+      colored background.
+    * LightBG: the basic colors are similar to those in the Linux scheme
+      but darker. It is easy to read in terminals with light backgrounds.
+
+IPython uses colors for two main groups of things: prompts and
+tracebacks which are directly printed to the terminal, and the object
+introspection system which passes large sets of data through a pager.
+
+If you are seeing garbage sequences in your terminal and no colour, you
+may need to disable colours: run ``%colors NoColor`` inside IPython, or
+add this to a config file::
+
+    c.InteractiveShell.colors = 'NoColor'
+
+Colors in the pager
+-------------------
+
+On some systems, the default pager has problems with ANSI colour codes.
+To configure your default pager to allow these:
+
+1. Set the environment PAGER variable to ``less``.
+2. Set the environment LESS variable to ``-r`` (plus any other options
+   you always want to pass to less by default). This tells less to
+   properly interpret control sequences, which is how color
+   information is given to your terminal.
+
+.. _editors:
+
+Editor configuration
+====================
+
+IPython can integrate with text editors in a number of different ways:
+
+* Editors (such as `(X)Emacs`_, vim_ and TextMate_) can
+  send code to IPython for execution.
+
+* IPython's ``%edit`` magic command can open an editor of choice to edit
+  a code block.
+
+The %edit command (and its alias %ed) will invoke the editor set in your
+environment as :envvar:`EDITOR`. If this variable is not set, it will default
+to vi under Linux/Unix and to notepad under Windows. You may want to set this
+variable properly and to a lightweight editor which doesn't take too long to
+start (that is, something other than a new instance of Emacs). This way you
+can edit multi-line code quickly and with the power of a real editor right
+inside IPython.
+
+You can also control the editor by setting :attr:`TerminalInteractiveShell.editor`
+in :file:`ipython_config.py`.
+
+Vim
+---
+
+Paul Ivanov's `vim-ipython <https://github.com/ivanov/vim-ipython>`_ provides
+powerful IPython integration for vim.
+
+.. _emacs:
+
+(X)Emacs
+--------
+
+If you are a dedicated Emacs user, and want to use Emacs when IPython's
+``%edit`` magic command is called you should set up the Emacs server so that
+new requests are handled by the original process. This means that almost no
+time is spent in handling the request (assuming an Emacs process is already
+running). For this to work, you need to set your EDITOR environment variable
+to 'emacsclient'. The code below, supplied by Francois Pinard, can then be
+used in your :file:`.emacs` file to enable the server:
+
+.. code-block:: common-lisp
+
+    (defvar server-buffer-clients)
+    (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
+      (server-start)
+      (defun fp-kill-server-with-buffer-routine ()
+        (and server-buffer-clients (server-done)))
+      (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
+
+Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
+currently (X)Emacs and IPython get along very well in other ways.
+
+.. note::
+
+    You will need to use a recent enough version of :file:`python-mode.el`,
+    along with the file :file:`ipython.el`. You can check that the version you
+    have of :file:`python-mode.el` is new enough by either looking at the
+    revision number in the file itself, or asking for it in (X)Emacs via ``M-x
+    py-version``. Versions 4.68 and newer contain the necessary fixes for
+    proper IPython support.
+
+The file :file:`ipython.el` is included with the IPython distribution, in the
+directory :file:`docs/emacs`. Once you put these files in your Emacs path, all
+you need in your :file:`.emacs` file is:
+
+.. code-block:: common-lisp
+
+    (require 'ipython)
+
+This should give you full support for executing code snippets via
+IPython, opening IPython as your Python shell via ``C-c !``, etc.
+
+You can customize the arguments passed to the IPython instance at startup by
+setting the ``py-python-command-args`` variable.  For example, to start always
+with ``matplotlib`` integration and hardcoded light-background colors, you can use:
+
+.. code-block:: common-lisp
+
+    (setq py-python-command-args '("--matplotlib" "--colors" "LightBG"))
+
+If you happen to get garbage instead of colored prompts as described in
+the previous section, you may need to set also in your :file:`.emacs` file:
+
+.. code-block:: common-lisp
+
+    (setq ansi-color-for-comint-mode t)
+
+Notes on emacs support:
+
+.. This looks hopelessly out of date - can someone update it?
+
+* There is one caveat you should be aware of: you must start the IPython shell
+  before attempting to execute any code regions via ``C-c |``. Simply type
+  ``C-c !`` to start IPython before passing any code regions to the
+  interpreter, and you shouldn't experience any problems. This is due to a bug
+  in Python itself, which has been fixed for Python 2.3, but exists as of
+  Python 2.2.2 (reported as SF bug [ 737947 ]).
+
+* The (X)Emacs support is maintained by Alexander Schmolck, so all
+  comments/requests should be directed to him through the IPython mailing
+  lists.
+
+* This code is still somewhat experimental so it's a bit rough around the
+  edges (although in practice, it works quite well).
+
+* Be aware that if you customized ``py-python-command`` previously, this value
+  will override what :file:`ipython.el` does (because loading the customization
+  variables comes later).
+
+.. _`(X)Emacs`: http://www.gnu.org/software/emacs/
+.. _TextMate: http://macromates.com/
+.. _vim: http://www.vim.org/

docs/source/config/intro.rst

@@ -0,0 +1,156 b''
+=====================================
+Introduction to IPython configuration
+=====================================
+
+.. _setting_config:
+
+Setting configurable options
+============================
+
+Many of IPython's classes have configurable attributes (see
+:doc:`options/index` for the list). These can be
+configured in several ways.
+
+Python config files
+-------------------
+
+To create the blank config files, run::
+
+    ipython profile create [profilename]
+
+If you leave out the profile name, the files will be created for the
+``default`` profile (see :ref:`profiles`). These will typically be
+located in :file:`~/.ipython/profile_default/`, and will be named
+:file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
+The settings in :file:`ipython_config.py` apply to all IPython commands.
+
+The files typically start by getting the root config object::
+
+    c = get_config()
+
+You can then configure class attributes like this::
+
+    c.InteractiveShell.automagic = False
+
+Be careful with spelling--incorrect names will simply be ignored, with
+no error.
+
+To add to a collection which may have already been defined elsewhere,
+you can use methods like those found on lists, dicts and sets: append,
+extend, :meth:`~IPython.config.loader.LazyConfigValue.prepend` (like
+extend, but at the front), add and update (which works both for dicts
+and sets)::
+
+    c.InteractiveShellApp.extensions.append('rmagic')
+
+.. versionadded:: 2.0
+   list, dict and set methods for config values
+
+Example config file
+```````````````````
+
+::
+
+    # sample ipython_config.py
+    c = get_config()
+
+    c.TerminalIPythonApp.display_banner = True
+    c.InteractiveShellApp.log_level = 20
+    c.InteractiveShellApp.extensions = [
+        'myextension'
+    ]
+    c.InteractiveShellApp.exec_lines = [
+        'import numpy',
+        'import scipy'
+    ]
+    c.InteractiveShellApp.exec_files = [
+        'mycode.py',
+        'fancy.ipy'
+    ]
+    c.InteractiveShell.autoindent = True
+    c.InteractiveShell.colors = 'LightBG'
+    c.InteractiveShell.confirm_exit = False
+    c.InteractiveShell.deep_reload = True
+    c.InteractiveShell.editor = 'nano'
+    c.InteractiveShell.xmode = 'Context'
+
+    c.PromptManager.in_template  = 'In [\#]: '
+    c.PromptManager.in2_template = '   .\D.: '
+    c.PromptManager.out_template = 'Out[\#]: '
+    c.PromptManager.justify = True
+
+    c.PrefilterManager.multi_line_specials = True
+
+    c.AliasManager.user_aliases = [
+     ('la', 'ls -al')
+    ]
+
+
+Command line arguments
+----------------------
+
+Every configurable value can be set from the command line, using this
+syntax::
+
+    ipython --ClassName.attribute=value
+
+Many frequently used options have short aliases and flags, such as
+``--matplotlib`` (to integrate with a matplotlib GUI event loop) or
+``--pdb`` (automatic post-mortem debugging of exceptions).
+
+To see all of these abbreviated options, run::
+
+    ipython --help
+    ipython notebook --help
+    # etc.
+
+Options specified at the command line, in either format, override
+options set in a configuration file.
+
+The config magic
+----------------
+
+You can also modify config from inside IPython, using a magic command::
+
+    %config IPCompleter.greedy = True
+
+At present, this only affects the current session - changes you make to
+config are not saved anywhere. Also, some options are only read when
+IPython starts, so they can't be changed like this.
+
+.. _profiles:
+
+Profiles
+========
+
+IPython can use multiple profiles, with separate configuration and
+history. By default, if you don't specify a profile, IPython always runs
+in the ``default`` profile. To use a new profile::
+
+    ipython profile create foo   # create the profile foo
+    ipython --profile=foo        # start IPython using the new profile
+
+Profiles are typically stored in :ref:`ipythondir`, but you can also keep
+a profile in the current working directory, for example to distribute it
+with a project. To find a profile directory on the filesystem::
+
+    ipython locate profile foo
+
+.. _ipythondir:
+
+The IPython directory
+=====================
+
+IPython stores its files---config, command history and extensions---in
+the directory :file:`~/.ipython/` by default.
+
+.. envvar:: IPYTHONDIR
+
+   If set, this environment variable should be the path to a directory,
+   which IPython will use for user data. IPython will create it if it
+   does not exist.
+
+.. option:: --ipython-dir=<path>
+
+   This command line option can also be used to override the default
+   IPython directory.

docs/source/config/options/index.rst

@@ -0,0 +1,14 b''
+===============
+IPython options
+===============
+
+Any of the options listed here can be set in config files, at the
+command line, or from inside IPython. See :ref:`setting_config` for
+details.
+
+.. toctree::
+
+   terminal
+   kernel
+   notebook
+   qtconsole

.gitignore

@@ -4,6 +4,7 b' dist'
 _build
 docs/man/*.gz
 docs/source/api/generated
+docs/source/config/options
 docs/gh-pages
 IPython/html/notebook/static/mathjax
 *.py[co]

IPython/core/shellapp.py

@@ -195,7 +195,7 b' class InteractiveShellApp(Configurable):'
     )
     pylab_import_all = Bool(True, config=True,
         help="""If true, IPython will populate the user namespace with numpy, pylab, etc.
-        and an 'import *' is done from numpy and pylab, when using pylab mode.
+        and an ``import *`` is done from numpy and pylab, when using pylab mode.
         
         When False, pylab mode should not import any names into the user namespace.
         """

IPython/qt/console/console_widget.py

@@ -130,15 +130,18 b" class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui."
         help="""
         The type of paging to use. Valid values are:
 
-            'inside' : The widget pages like a traditional terminal.
-            'hsplit' : When paging is requested, the widget is split
-                       horizontally. The top pane contains the console, and the
-                       bottom pane contains the paged text.
-            'vsplit' : Similar to 'hsplit', except that a vertical splitter
-                       used.
-            'custom' : No action is taken by the widget beyond emitting a
-                       'custom_page_requested(str)' signal.
-            'none'   : The text is written directly to the console.
+        'inside'
+           The widget pages like a traditional terminal.
+        'hsplit'
+           When paging is requested, the widget is split horizontally. The top
+           pane contains the console, and the bottom pane contains the paged text.
+        'vsplit'
+           Similar to 'hsplit', except that a vertical splitter is used.
+        'custom'
+           No action is taken by the widget beyond emitting a
+           'custom_page_requested(str)' signal.
+        'none'
+           The text is written directly to the console.
         """)
 
     font_family = Unicode(config=True,

docs/Makefile

@@ -40,6 +40,7 b' clean_api:'
 
 clean: clean_api
 	-rm -rf build/* dist/*
+	-rm -rf $(SRCDIR)/config/options/generated
 
 pdf: latex
 	cd build/latex && make all-pdf
@@ -56,8 +57,8 b' dist: html'
 	cp -al build/html .
 	@echo "Build finished.  Final docs are in html/"
 
-html: api 
-html_noapi: clean_api
+html: api autoconfig
+html_noapi: clean_api autoconfig
 
 html html_noapi:
 	mkdir -p build/html build/doctrees
@@ -65,6 +66,12 b' html html_noapi:'
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
+autoconfig: source/config/options/generated
+
+source/config/options/generated:
+	python autogen_config.py
+	@echo "Created docs for config options"
+
 api: source/api/generated/gen.txt
 
 source/api/generated/gen.txt:
@@ -98,7 +105,7 b' qthelp:'
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
 
-latex: api
+latex: api autoconfig
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	@echo

docs/source/_static/default.css

@@ -120,6 +120,11 b' dd {'
     color: #060;
 }
 
+dt {
+    font-weight: bold;
+    padding-left: 0.5em;
+}
+
 dt:target,
 .highlight {
     background-color: #fbe54e;
@@ -480,6 +485,12 b' span.linkdescr {'
     font-size: 90%;
 }
 
+.search input[name=q] {
+    max-width: 100%;
+    box-sizing: border-box;
+    -moz-box-sizing: border-box;
+}
+
 ul.search {
     margin: 10px 0 0 20px;
     padding: 0;

docs/source/config/index.rst

@@ -4,13 +4,27 b''
 Configuration and customization
 ===============================
 
+Configuring IPython
+-------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   options/index
+   details
+
+.. seealso::
+
+   :doc:`/development/config`
+      Technical details of the config system.
+
+Extending and integrating with IPython
+--------------------------------------
+
 .. toctree::
    :maxdepth: 2
 
-   overview
    extensions/index
-   ipython
    integrating
-   editors
    inputtransforms
-   old

docs/source/development/config.rst

@@ -6,11 +6,6 b' Overview of the IPython configuration system'
 
 This section describes the IPython configuration system. 
 
-The following discussion is for users who want to configure
-IPython to their liking.  Developers who want to know how they can
-enable their objects to take advantage of the configuration system
-should consult the :ref:`developer guide <developer_guide>`
-
 The main concepts
 =================
 
@@ -324,7 +319,7 b' These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir`'
 and :func:`IPython.utils.path.locate_profile` respectively.
 
 
-.. _Profiles:
+.. _profiles_dev:
 
 Profiles
 ========

docs/source/development/index.rst

@@ -25,3 +25,4 b' on the IPython GitHub wiki.'
    parallel_messages
    parallel_connections
    pycompat
+   config

docs/source/whatsnew/version0.11.rst

@@ -547,12 +547,12 b' Backwards incompatible changes'
 
 * Old style configuration files :file:`ipythonrc` and :file:`ipy_user_conf.py`
   are no longer supported. Users should migrate there configuration files to
-  the new format described :ref:`here <config_overview>` and :ref:`here
-  <configuring_ipython>`.
+  the new format described :doc:`here <config/intro>` and
+  :ref:`here <config_overview>`.
 
 * The old IPython extension API that relied on :func:`ipapi` has been
   completely removed. The new extension API is described :ref:`here
-  <configuring_ipython>`.
+  <extensions_overview>`.
 
 * Support for ``qt3`` has been dropped.  Users who need this should use
   previous versions of IPython.