Improve documentation for extensions, and for storemagic extension.

docs/source/config/extensions/storemagic.txt

@@ -0,0 +1,8 b''
+.. _extensions_storemagic:
+
+==========
+storemagic
+==========
+
+.. automodule:: IPython.extensions.storemagic
+   :members: magic_store

IPython/core/interactiveshell.py

@@ -2000,14 +2000,16 b' class InteractiveShell(SingletonConfigurable, Magic):'
 
     def define_magic(self, magicname, func):
         """Expose own function as magic function for ipython
+        
+        Example::
 
-        def foo_impl(self,parameter_s=''):
-            'My very own magic!. (Use docstrings, IPython reads them).'
-            print 'Magic function. Passed parameter is between < >:'
-            print '<%s>' % parameter_s
-            print 'The self object is:',self
+          def foo_impl(self,parameter_s=''):
+              'My very own magic!. (Use docstrings, IPython reads them).'
+              print 'Magic function. Passed parameter is between < >:'
+              print '<%s>' % parameter_s
+              print 'The self object is:', self
 
-        self.define_magic('foo',foo_impl)
+          ip.define_magic('foo',foo_impl)
         """
         im = types.MethodType(func,self)
         old = getattr(self, "magic_" + magicname, None)

IPython/extensions/storemagic.py

@@ -2,16 +2,18 b''
 """
 %store magic for lightweight persistence.
 
-Stores variables, aliases etc. in PickleShare database.
+Stores variables, aliases and macros in IPython's database. Stored values will
+be automatically restored whenever the extension is loaded.
 
-To enable this functionality, run::
+To enable this functionality, list it in your default profile
+`ipython_config.py` file::
 
-  %load_ext storemagic
+  c.InteractiveShellApp.extensions = ['storemagic']
 
-in your IPython session.  If you always want it enabled, you can list it in
-your default profile `ipython_config.py` file::
+Or to use it temporarily, run this in your IPython session::
+
+  %load_ext storemagic
 
-  c.InteractiveShellApp.extensions = ['storemagic']
 """
 
 from IPython.core.error import TryNext, UsageError
@@ -54,34 +56,33 b' def restore_data(ip):'
 def magic_store(self, parameter_s=''):
     """Lightweight persistence for python variables.
 
-    Example:
-
-    ville@badger[~]|1> A = ['hello',10,'world']\\
-    ville@badger[~]|2> %store A\\
-    ville@badger[~]|3> Exit
+    Example::
 
-    (IPython session is closed and started again...)
+      In [1]: l = ['hello',10,'world']
+      In [2]: %store l
+      In [3]: exit
 
-    ville@badger:~$ ipython -p pysh\\
-    ville@badger[~]|1> print A
+      (IPython session is closed and started again...)
 
-    ['hello', 10, 'world']
+      ville@badger:~$ ipython
+      In [1]: l
+      Out[1]: ['hello', 10, 'world']
 
     Usage:
 
-    %store          - Show list of all variables and their current values\\
-    %store <var>    - Store the *current* value of the variable to disk\\
-    %store -d <var> - Remove the variable and its value from storage\\
-    %store -z       - Remove all variables from storage\\
-    %store -r       - Refresh all variables from store (delete current vals)\\
-    %store foo >a.txt  - Store value of foo to new file a.txt\\
-    %store foo >>a.txt - Append value of foo to file a.txt\\
+    * ``%store``          - Show list of all variables and their current values
+    * ``%store spam``     - Store the *current* value of the variable spam to disk
+    * ``%store -d spam``  - Remove the variable and its value from storage
+    * ``%store -z``       - Remove all variables from storage
+    * ``%store -r``       - Refresh all variables from store (delete current vals)
+    * ``%store foo >a.txt``  - Store value of foo to new file a.txt
+    * ``%store foo >>a.txt`` - Append value of foo to file a.txt
 
     It should be noted that if you change the value of a variable, you
     need to %store it again if you want to persist the new value.
 
     Note also that the variables will need to be pickleable; most basic
-    python types can be safely %stored.
+    python types can be safely %store'd.
 
     Also aliases can be %store'd across sessions.
     """

docs/source/config/extensions/index.txt

@@ -29,6 +29,10 b' The :func:`load_ipython_extension` will be called again is you load or reload'
 the extension again. It is up to the extension author to add code to manage
 that.
 
+Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`, 
+:meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and 
+:meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
+
 You can put your extension modules anywhere you want, as long as they can be
 imported by Python's standard import mechanism. However, to make it easy to
 write extensions, you can also put your extensions in
@@ -68,4 +72,5 b' Extensions bundled with IPython'
 
    autoreload
    parallelmagic
+   storemagic
    sympyprinting

docs/source/whatsnew/development.txt

@@ -62,7 +62,7 b' New features'
   Terminal frontend by default (:ghpull:`838`).
 
 * **%store**: The ``%store`` magic from earlier versions has been updated and
-  placed in an extension, 'storemagic'. Add 'storemagic' to ``c.InteractiveShellApp.extensions``
+  placed in an extension, :ref:`extensions_storemagic`. Add 'storemagic' to ``c.InteractiveShellApp.extensions``
   in ipython_config.py to enable it (:ghpull:`1029`).