Pull docs on defining magics out to customisation section

docs/source/config/custommagics.rst

@@ -0,0 +1,132 b''
+.. _defining_magics:
+
+Defining custom magics
+======================
+
+There are two main ways to define your own magic functions: from standalone
+functions and by inheriting from a base class provided by IPython:
+:class:`IPython.core.magic.Magics`. Below we show code you can place in a file
+that you load from your configuration, such as any file in the ``startup``
+subdirectory of your default IPython profile.
+
+First, let us see the simplest case. The following shows how to create a line
+magic, a cell one and one that works in both modes, using just plain functions:
+
+.. sourcecode:: python
+
+    from IPython.core.magic import (register_line_magic, register_cell_magic,
+                                    register_line_cell_magic)
+
+    @register_line_magic
+    def lmagic(line):
+        "my line magic"
+        return line
+
+    @register_cell_magic
+    def cmagic(line, cell):
+        "my cell magic"
+        return line, cell
+
+    @register_line_cell_magic
+    def lcmagic(line, cell=None):
+        "Magic that works both as %lcmagic and as %%lcmagic"
+        if cell is None:
+            print("Called as line magic")
+            return line
+        else:
+            print("Called as cell magic")
+            return line, cell
+
+    # We delete these to avoid name conflicts for automagic to work
+    del lmagic, lcmagic
+
+
+You can also create magics of all three kinds by inheriting from the
+:class:`IPython.core.magic.Magics` class.  This lets you create magics that can
+potentially hold state in between calls, and that have full access to the main
+IPython object:
+    
+.. sourcecode:: python
+
+    # This code can be put in any Python module, it does not require IPython
+    # itself to be running already.  It only creates the magics subclass but
+    # doesn't instantiate it yet.
+    from __future__ import print_function
+    from IPython.core.magic import (Magics, magics_class, line_magic,
+                                    cell_magic, line_cell_magic)
+
+    # The class MUST call this class decorator at creation time
+    @magics_class
+    class MyMagics(Magics):
+
+        @line_magic
+        def lmagic(self, line):
+            "my line magic"
+            print("Full access to the main IPython object:", self.shell)
+            print("Variables in the user namespace:", list(self.shell.user_ns.keys()))
+            return line
+
+        @cell_magic
+        def cmagic(self, line, cell):
+            "my cell magic"
+            return line, cell
+
+        @line_cell_magic
+        def lcmagic(self, line, cell=None):
+            "Magic that works both as %lcmagic and as %%lcmagic"
+            if cell is None:
+                print("Called as line magic")
+                return line
+            else:
+                print("Called as cell magic")
+                return line, cell
+
+
+    # In order to actually use these magics, you must register them with a
+    # running IPython.  This code must be placed in a file that is loaded once
+    # IPython is up and running:
+    ip = get_ipython()
+    # You can register the class itself without instantiating it.  IPython will
+    # call the default constructor on it.
+    ip.register_magics(MyMagics)
+
+If you want to create a class with a different constructor that holds
+additional state, then you should always call the parent constructor and
+instantiate the class yourself before registration:
+
+.. sourcecode:: python
+
+    @magics_class
+    class StatefulMagics(Magics):
+        "Magics that hold additional state"
+
+        def __init__(self, shell, data):
+            # You must call the parent constructor
+            super(StatefulMagics, self).__init__(shell)
+            self.data = data
+        
+        # etc...
+
+    # This class must then be registered with a manually created instance,
+    # since its constructor has different arguments from the default:
+    ip = get_ipython()
+    magics = StatefulMagics(ip, some_data)
+    ip.register_magics(magics)
+    
+
+In earlier versions, IPython had an API for the creation of line magics (cell
+magics did not exist at the time) that required you to create functions with a
+method-looking signature and to manually pass both the function and the name.
+While this API is no longer recommended, it remains indefinitely supported for
+backwards compatibility purposes.  With the old API, you'd create a magic as
+follows:
+
+.. sourcecode:: python
+
+    def func(self, line):
+        print("Line magic called with line:", line)
+        print("IPython object:", self.shell)
+
+    ip = get_ipython()
+    # Declare this function as the magic %mycommand
+    ip.define_magic('mycommand', func)

docs/source/config/index.rst

@@ -27,5 +27,6 b' Extending and integrating with IPython'
 
    extensions/index
    integrating
+   custommagics
    inputtransforms
    callbacks

docs/source/interactive/reference.rst

@@ -145,139 +145,6 b' use it:'
 
     /home/fperez/ipython
 
-.. _defining_magics:
-
-Defining your own magics
-++++++++++++++++++++++++
-
-There are two main ways to define your own magic functions: from standalone
-functions and by inheriting from a base class provided by IPython:
-:class:`IPython.core.magic.Magics`.  Below we show code you can place in a file
-that you load from your configuration, such as any file in the ``startup``
-subdirectory of your default IPython profile.
-
-First, let us see the simplest case.  The following shows how to create a line
-magic, a cell one and one that works in both modes, using just plain functions:
-
-.. sourcecode:: python
-
-    from IPython.core.magic import (register_line_magic, register_cell_magic,
-                                    register_line_cell_magic)
-
-    @register_line_magic
-    def lmagic(line):
-        "my line magic"
-        return line
-
-    @register_cell_magic
-    def cmagic(line, cell):
-        "my cell magic"
-        return line, cell
-
-    @register_line_cell_magic
-    def lcmagic(line, cell=None):
-        "Magic that works both as %lcmagic and as %%lcmagic"
-        if cell is None:
-            print("Called as line magic")
-            return line
-        else:
-            print("Called as cell magic")
-            return line, cell
-
-    # We delete these to avoid name conflicts for automagic to work
-    del lmagic, lcmagic
-
-
-You can also create magics of all three kinds by inheriting from the
-:class:`IPython.core.magic.Magics` class.  This lets you create magics that can
-potentially hold state in between calls, and that have full access to the main
-IPython object:
-    
-.. sourcecode:: python
-
-    # This code can be put in any Python module, it does not require IPython
-    # itself to be running already.  It only creates the magics subclass but
-    # doesn't instantiate it yet.
-    from __future__ import print_function
-    from IPython.core.magic import (Magics, magics_class, line_magic,
-                                    cell_magic, line_cell_magic)
-
-    # The class MUST call this class decorator at creation time
-    @magics_class
-    class MyMagics(Magics):
-
-        @line_magic
-        def lmagic(self, line):
-            "my line magic"
-            print("Full access to the main IPython object:", self.shell)
-            print("Variables in the user namespace:", list(self.shell.user_ns.keys()))
-            return line
-
-        @cell_magic
-        def cmagic(self, line, cell):
-            "my cell magic"
-            return line, cell
-
-        @line_cell_magic
-        def lcmagic(self, line, cell=None):
-            "Magic that works both as %lcmagic and as %%lcmagic"
-            if cell is None:
-                print("Called as line magic")
-                return line
-            else:
-                print("Called as cell magic")
-                return line, cell
-
-
-    # In order to actually use these magics, you must register them with a
-    # running IPython.  This code must be placed in a file that is loaded once
-    # IPython is up and running:
-    ip = get_ipython()
-    # You can register the class itself without instantiating it.  IPython will
-    # call the default constructor on it.
-    ip.register_magics(MyMagics)
-
-If you want to create a class with a different constructor that holds
-additional state, then you should always call the parent constructor and
-instantiate the class yourself before registration:
-
-.. sourcecode:: python
-
-    @magics_class
-    class StatefulMagics(Magics):
-        "Magics that hold additional state"
-
-        def __init__(self, shell, data):
-            # You must call the parent constructor
-            super(StatefulMagics, self).__init__(shell)
-            self.data = data
-        
-        # etc...
-
-    # This class must then be registered with a manually created instance,
-    # since its constructor has different arguments from the default:
-    ip = get_ipython()
-    magics = StatefulMagics(ip, some_data)
-    ip.register_magics(magics)
-    
-
-In earlier versions, IPython had an API for the creation of line magics (cell
-magics did not exist at the time) that required you to create functions with a
-method-looking signature and to manually pass both the function and the name.
-While this API is no longer recommended, it remains indefinitely supported for
-backwards compatibility purposes.  With the old API, you'd create a magic as
-follows:
-
-.. sourcecode:: python
-
-    def func(self, line):
-        print("Line magic called with line:", line)
-        print("IPython object:", self.shell)
-
-    ip = get_ipython()
-    # Declare this function as the magic %mycommand
-    ip.define_magic('mycommand', func)
-
 Type ``%magic`` for more information, including a list of all available magic
 functions at any time and their docstrings. You can also type
 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
@@ -287,6 +154,11 b' function you are interested in.'
 The API documentation for the :mod:`IPython.core.magic` module contains the full
 docstrings of all currently available magic commands.
 
+.. seealso::
+
+   :ref:`defining_magics`
+     How to define and register additional magic functions
+
 
 Access to the standard Python help
 ----------------------------------