From e33abb35b5d0dccf680b6a9856c7985abec4f032 2013-11-07 23:50:51 From: Min RK Date: 2013-11-07 23:50:51 Subject: [PATCH] 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. --- diff --git a/.gitignore b/.gitignore index 703b7bc..8c1d8b2 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ dist _build docs/man/*.gz docs/source/api/generated +docs/source/config/options docs/gh-pages IPython/html/notebook/static/mathjax *.py[co] diff --git a/IPython/core/shellapp.py b/IPython/core/shellapp.py index 5b0cecf..6aed2e7 100644 --- a/IPython/core/shellapp.py +++ b/IPython/core/shellapp.py @@ -195,7 +195,7 @@ 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. """ diff --git a/IPython/qt/console/console_widget.py b/IPython/qt/console/console_widget.py index 3d10053..b108ff3 100644 --- a/IPython/qt/console/console_widget.py +++ b/IPython/qt/console/console_widget.py @@ -130,15 +130,18 @@ 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, diff --git a/docs/Makefile b/docs/Makefile index 6d20ed1..f835fdf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -40,6 +40,7 @@ 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 @@ 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 @@ 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 @@ 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 diff --git a/docs/autogen_config.py b/docs/autogen_config.py new file mode 100644 index 0000000..a2538b4 --- /dev/null +++ b/docs/autogen_config.py @@ -0,0 +1,74 @@ +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 diff --git a/docs/source/_static/default.css b/docs/source/_static/default.css index ea605da..38544c6 100644 --- a/docs/source/_static/default.css +++ b/docs/source/_static/default.css @@ -120,6 +120,11 @@ dd { color: #060; } +dt { + font-weight: bold; + padding-left: 0.5em; +} + dt:target, .highlight { background-color: #fbe54e; @@ -480,6 +485,12 @@ 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; diff --git a/docs/source/config/details.rst b/docs/source/config/details.rst new file mode 100644 index 0000000..0c4f7aa --- /dev/null +++ b/docs/source/config/details.rst @@ -0,0 +1,234 @@ +======================= +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.} 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 `_ 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/ diff --git a/docs/source/config/editors.rst b/docs/source/config/editors.rst deleted file mode 100644 index 2095db5..0000000 --- a/docs/source/config/editors.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _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`. - -TextMate -======== - -Currently, TextMate support in IPython is broken. It used to work well, -but the code has been moved to :mod:`IPython.quarantine` until it is updated. - -Vim -=== - -Paul Ivanov's `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:: - - (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:: - - (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:: - - (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:: - - (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/ diff --git a/docs/source/config/index.rst b/docs/source/config/index.rst index 38e206c..46fa2d9 100644 --- a/docs/source/config/index.rst +++ b/docs/source/config/index.rst @@ -4,13 +4,27 @@ 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 diff --git a/docs/source/config/intro.rst b/docs/source/config/intro.rst new file mode 100644 index 0000000..0103b67 --- /dev/null +++ b/docs/source/config/intro.rst @@ -0,0 +1,156 @@ +===================================== +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= + + This command line option can also be used to override the default + IPython directory. diff --git a/docs/source/config/ipython.rst b/docs/source/config/ipython.rst deleted file mode 100644 index c518a1b..0000000 --- a/docs/source/config/ipython.rst +++ /dev/null @@ -1,138 +0,0 @@ -.. _configuring_ipython: - -=========================================================== -Configuring the :command:`ipython` command line application -=========================================================== - -This section contains information about how to configure the -:command:`ipython` command line application. See the :ref:`configuration -overview ` for a more general description of the -configuration system and configuration file format. - -The default configuration file for the :command:`ipython` command line application -is :file:`profile_default/ipython_config.py` in your :ref:`IPython directory -`. By setting the attributes in this file, you can configure the -application. To create the default config file, run this command:: - - $ ipython profile create - -Most configuration attributes that this file accepts are associated with classes -that are subclasses of :class:`~IPython.config.configurable.Configurable`. - -Applications themselves are Configurable as well, so we will start with some -application-level config. - -Application-level configuration -=============================== - -Assuming that your configuration file has the following at the top:: - - c = get_config() - -the following attributes are set application-wide: - -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.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.TerminalIPythonApp.nosep` - A boolean that determines if there should be no blank lines between - prompts. - -: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.InteractiveShellApp.extensions` - A list of strings, each of which is an importable IPython extension. See - :ref:`extensions_overview` for more details about extensions. - -: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.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 - be pure Python. Files with a ``.ipy`` extension can have custom IPython - syntax (magics, etc.). These files need to be in the cwd, the ipythondir - or be absolute paths. - -Classes that can be configured -============================== - -The following classes can also be configured in the configuration file for -:command:`ipython`: - -* :class:`~IPython.core.interactiveshell.InteractiveShell` - -* :class:`~IPython.core.prefilter.PrefilterManager` - -* :class:`~IPython.core.alias.AliasManager` - -To see which attributes of these classes are configurable, please see the -source code for these classes, the class docstrings or the sample -configuration file :mod:`IPython.config.default.ipython_config`. - -Example -======= - -For those who want to get a quick start, here is a sample -:file:`ipython_config.py` that sets some of the common configuration -attributes:: - - # 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') - ] diff --git a/docs/source/config/old.rst b/docs/source/config/old.rst deleted file mode 100644 index da67569..0000000 --- a/docs/source/config/old.rst +++ /dev/null @@ -1,230 +0,0 @@ -.. _initial config: - -============================================================= -Outdated configuration information that might still be useful -============================================================= - -.. warning:: - - All of the information in this file is outdated. Until the new - configuration system is better documented, this material is being kept. - -This section will help you set various things in your environment for -your IPython sessions to be as efficient as possible. All of IPython's -configuration information, along with several example files, is stored -in a directory named by default $HOME/.ipython. You can change this by -defining the environment variable IPYTHONDIR, or at runtime with the -command line option -ipythondir. - -If all goes well, the first time you run IPython it should automatically create -a user copy of the config directory for you, based on its builtin defaults. You -can look at the files it creates to learn more about configuring the -system. The main file you will modify to configure IPython's behavior is called -ipythonrc (with a .ini extension under Windows), included for reference -:ref:`here `. This file is very commented and has many variables you -can change to suit your taste, you can find more details :ref:`here -`. Here we discuss the basic things you will want to make sure -things are working properly from the beginning. - -Color -===== - -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. - -Input/Output prompts and exception tracebacks -============================================= - -You can test whether the colored prompts and tracebacks work on your -system interactively by typing '%colors Linux' at the prompt (use -'%colors LightBG' if your terminal has a light background). If the input -prompt shows garbage like:: - - [0;32mIn [[1;32m1[0;32m]: [0;00m - -instead of (in color) something like:: - - In [1]: - -this means that your terminal doesn't properly handle color escape -sequences. You can go to a 'no color' mode by typing '%colors NoColor'. - -You can try using a different terminal emulator program (Emacs users, -see below). To permanently set your color preferences, edit the file -$IPYTHONDIR/ipythonrc and set the colors option to the desired value. - - -Object details (types, docstrings, source code, etc.) -===================================================== - -IPython has a set of special functions for studying the objects you are working -with, discussed in detail :ref:`here `. But this system -relies on passing information which is longer than your screen through a data -pager, such as the common Unix less and more programs. In order to be able to -see this information in color, your pager needs to be properly configured. I -strongly recommend using less instead of more, as it seems that more simply can -not understand colored text correctly. - -In order to configure less as your default pager, do the following: - - 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. - -For the bash shell, add to your ~/.bashrc file the lines:: - - export PAGER=less - export LESS=-r - -For the csh or tcsh shells, add to your ~/.cshrc file the lines:: - - setenv PAGER less - setenv LESS -r - -There is similar syntax for other Unix shells, look at your system -documentation for details. - -If you are on a system which lacks proper data pagers (such as Windows), -IPython will use a very limited builtin pager. - -.. _Prompts: - -Fine-tuning your prompt -======================= - -IPython's prompts can be customized using a syntax similar to that of -the bash shell. Many of bash's escapes are supported, as well as a few -additional ones. We list them below:: - - \# - the prompt/history count number. This escape is automatically - wrapped in the coloring codes for the currently active color scheme. - \N - the 'naked' prompt/history count number: this is just the number - itself, without any coloring applied to it. This lets you produce - numbered prompts with your own colors. - \D - the prompt/history count, with the actual digits replaced by dots. - Used mainly in continuation prompts (prompt_in2) - \w - the current working directory - \W - the basename of current working directory - \Xn - where $n=0\ldots5.$ The current working directory, with $HOME - replaced by ~, and filtered out to contain only $n$ path elements - \Yn - Similar to \Xn, but with the $n+1$ element included if it is ~ (this - is similar to the behavior of the %cn escapes in tcsh) - \u - the username of the current user - \$ - if the effective UID is 0, a #, otherwise a $ - \h - the hostname up to the first '.' - \H - the hostname - \n - a newline - \r - a carriage return - \v - IPython version string - -In addition to these, ANSI color escapes can be insterted into the -prompts, as \C_ColorName. The list of valid color names is: Black, Blue, -Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, -LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White, -Yellow. - -Finally, IPython supports the evaluation of arbitrary expressions in -your prompt string. The prompt strings are evaluated through the syntax -of PEP 215, but basically you can use $x.y to expand the value of x.y, -and for more complicated expressions you can use braces: ${foo()+x} will -call function foo and add to it the value of x, before putting the -result into your prompt. For example, using -prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: ' -will print the result of the uptime command on each prompt (assuming the -commands module has been imported in your ipythonrc file). - - - Prompt examples - -The following options in an ipythonrc file will give you IPython's -default prompts:: - - prompt_in1 'In [\#]:' - prompt_in2 ' .\D.:' - prompt_out 'Out[\#]:' - -which look like this:: - - In [1]: 1+2 - Out[1]: 3 - - In [2]: for i in (1,2,3): - ...: print i, - ...: - 1 2 3 - -These will give you a very colorful prompt with path information:: - - #prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>' - prompt_in2 ' ..\D>' - prompt_out '<\#>' - -which look like this:: - - fperez[~/ipython]1> 1+2 - <1> 3 - fperez[~/ipython]2> for i in (1,2,3): - ...> print i, - ...> - 1 2 3 - - diff --git a/docs/source/config/options/index.rst b/docs/source/config/options/index.rst new file mode 100644 index 0000000..5004b7b --- /dev/null +++ b/docs/source/config/options/index.rst @@ -0,0 +1,14 @@ +=============== +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 diff --git a/docs/source/config/overview.rst b/docs/source/development/config.rst similarity index 97% rename from docs/source/config/overview.rst rename to docs/source/development/config.rst index 413cb00..d92e377 100644 --- a/docs/source/config/overview.rst +++ b/docs/source/development/config.rst @@ -6,11 +6,6 @@ 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 ` - The main concepts ================= @@ -324,7 +319,7 @@ 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 ======== diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 1240ef8..be82d74 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -25,3 +25,4 @@ on the IPython GitHub wiki. parallel_messages parallel_connections pycompat + config diff --git a/docs/source/whatsnew/version0.11.rst b/docs/source/whatsnew/version0.11.rst index d55aaf3..697684d 100644 --- a/docs/source/whatsnew/version0.11.rst +++ b/docs/source/whatsnew/version0.11.rst @@ -547,12 +547,12 @@ 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 ` and :ref:`here - `. + the new format described :doc:`here ` and + :ref:`here `. * The old IPython extension API that relied on :func:`ipapi` has been completely removed. The new extension API is described :ref:`here - `. + `. * Support for ``qt3`` has been dropped. Users who need this should use previous versions of IPython.