diff --git a/docs/source/config/details.rst b/docs/source/config/details.rst index 57a3628..27bd597 100644 --- a/docs/source/config/details.rst +++ b/docs/source/config/details.rst @@ -116,3 +116,111 @@ To configure your default pager to allow these: 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:: + + (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/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 4c08c49..6e3d182 100644 --- a/docs/source/config/index.rst +++ b/docs/source/config/index.rst @@ -10,6 +10,5 @@ Configuration and customization intro extensions/index integrating - editors inputtransforms details