From 9cf75bcba74f4016685b31cb73f916ff54fea686 2011-02-15 20:46:10
From: Thomas Kluyver <takowl@gmail.com>
Date: 2011-02-15 20:46:10
Subject: [PATCH] Merge branch 'magic-examples'

---

diff --git a/IPython/core/history.py b/IPython/core/history.py
index ba13aa5..1412623 100644
--- a/IPython/core/history.py
+++ b/IPython/core/history.py
@@ -24,6 +24,7 @@ import time
 # Our own packages
 import IPython.utils.io
 
+from IPython.testing import decorators as testdec
 from IPython.utils.pickleshare import PickleShareDB
 from IPython.utils.io import ask_yes_no
 from IPython.utils.warn import warn
@@ -305,6 +306,7 @@ class HistorySaveThread(threading.Thread):
         self.exit_now.set()
         self.join()
 
+@testdec.skip_doctest
 def magic_history(self, parameter_s = ''):
     """Print input history (_i<n> variables), with most recent last.
     
@@ -347,6 +349,15 @@ def magic_history(self, parameter_s = ''):
       -f FILENAME: instead of printing the output to the screen, redirect it to
        the given file.  The file is always overwritten, though IPython asks for
        confirmation first if it already exists.
+       
+    Examples
+    --------
+    ::
+    
+      In [6]: %hist -n 4 6
+      4:a = 12
+      5:print a**2
+
     """
 
     if not self.shell.displayhook.do_full_cache:
diff --git a/IPython/core/magic.py b/IPython/core/magic.py
index 0e071cb..cf3f537 100644
--- a/IPython/core/magic.py
+++ b/IPython/core/magic.py
@@ -575,10 +575,19 @@ Currently the magic system has the following functions:\n"""
         self.shell._inspect('pinfo', parameter_s, detail_level=1,
                             namespaces=namespaces)
 
+    @testdec.skip_doctest
     def magic_pdef(self, parameter_s='', namespaces=None):
         """Print the definition header for any callable object.
 
-        If the object is a class, print the constructor information."""
+        If the object is a class, print the constructor information.
+        
+        Examples
+        --------
+        ::
+        
+          In [3]: %pdef urllib.urlopen
+          urllib.urlopen(url, data=None, proxies=None)
+        """
         self._inspect('pdef',parameter_s, namespaces)
 
     def magic_pdoc(self, parameter_s='', namespaces=None):
@@ -2423,7 +2432,14 @@ Currently the magic system has the following functions:\n"""
 
         Currently implemented schemes: NoColor, Linux, LightBG.
 
-        Color scheme names are not case-sensitive."""
+        Color scheme names are not case-sensitive.
+        
+        Examples
+        --------
+        To get a plain black and white terminal::
+        
+          %colors nocolor
+        """
 
         def color_switch_err(name):
             warn('Error changing %s color schemes.\n%s' %
@@ -2660,11 +2676,21 @@ Defaulting color scheme to 'NoColor'"""
             db['syscmdlist'] = syscmdlist
         finally:
             os.chdir(savedir)
-        
+    
+    @testdec.skip_doctest    
     def magic_pwd(self, parameter_s = ''):
-        """Return the current working directory path."""
+        """Return the current working directory path.
+        
+        Examples
+        --------
+        ::
+        
+          In [9]: pwd
+          Out[9]: '/home/tsuser/sprint/ipython'
+        """
         return os.getcwd()
-
+    
+    @testdec.skip_doctest
     def magic_cd(self, parameter_s=''):
         """Change the current working directory.
 
@@ -2695,7 +2721,15 @@ Defaulting color scheme to 'NoColor'"""
         since the default prompts do not display path information.
         
         Note that !cd doesn't work for this purpose because the shell where
-        !command runs is immediately discarded after executing 'command'."""
+        !command runs is immediately discarded after executing 'command'.
+        
+        Examples
+        --------
+        ::
+        
+          In [10]: cd parent/child
+          /home/tsuser/parent/child
+        """
 
         parameter_s = parameter_s.strip()
         #bkms = self.shell.persist.get("bookmarks",{})
diff --git a/IPython/frontend/terminal/interactiveshell.py b/IPython/frontend/terminal/interactiveshell.py
index 671f82b..8f903d6 100644
--- a/IPython/frontend/terminal/interactiveshell.py
+++ b/IPython/frontend/terminal/interactiveshell.py
@@ -545,6 +545,17 @@ class TerminalInteractiveShell(InteractiveShell):
         See also
         --------
         paste: automatically pull code from clipboard.
+        
+        Examples
+        --------
+        ::
+        
+          In [8]: %cpaste
+          Pasting code; enter '--' alone on the line to stop.
+          :>>> a = ["world!", "Hello"]
+          :>>> print " ".join(sorted(a))
+          :--
+          Hello world!
         """
         
         opts,args = self.parse_options(parameter_s,'rs:',mode='string')