use `literalinclude` to embed examples in reference doc

also moved 'demo' examples into lib, since that's where demo is.

docs/examples/core/example-embed-short.py

@@ -25,9 +25,6 b' ipshell = InteractiveShellEmbed(banner1=banner, exit_msg=exit_msg)'
 # This code will load an embeddable IPython shell always with no changes for
 # nested embededings.
 
-# This code will load an embeddable IPython shell always with no changes for
-# nested embededings.
-
 from IPython import embed
 # Now embed() will open IPython anywhere in the code.
 

docs/source/interactive/reference.txt

@@ -1022,200 +1022,14 b' The following sample file illustrating how to use the embedding'
 functionality is provided in the examples directory as example-embed.py.
 It should be fairly self-explanatory:
 
-.. sourcecode:: python
-
-    #!/usr/bin/env python
-
-    """An example of how to embed an IPython shell into a running program.
-
-    Please see the documentation in the IPython.Shell module for more details.
-
-    The accompanying file example-embed-short.py has quick code fragments for
-    embedding which you can cut and paste in your code once you understand how
-    things work.
-
-    The code in this file is deliberately extra-verbose, meant for learning."""
-
-    # The basics to get you going:
-
-    # IPython sets the __IPYTHON__ variable so you can know if you have nested
-    # copies running.
-
-    # Try running this code both at the command line and from inside IPython (with
-    # %run example-embed.py)
-    from IPython.config.loader import Config
-    try:
-        get_ipython
-    except NameError:
-        nested = 0
-        cfg = Config()
-        shell_config = cfg.InteractiveShellEmbed
-        shell_config.prompt_in1 = 'In <\\#>: '
-        shell_config.prompt_in2 = '   .\\D.: '
-        shell_config.prompt_out = 'Out<\\#>: '
-    else:
-        print "Running nested copies of IPython."
-        print "The prompts for the nested copy have been modified"
-        cfg = Config()
-        nested = 1
-
-    # First import the embeddable shell class
-    from IPython.frontend.terminal.embed import InteractiveShellEmbed
-
-    # Now create an instance of the embeddable shell. The first argument is a
-    # string with options exactly as you would type them if you were starting
-    # IPython at the system command line. Any parameters you want to define for
-    # configuration can thus be specified here.
-    ipshell = InteractiveShellEmbed(config=cfg,
-                           banner1 = 'Dropping into IPython',
-                           exit_msg = 'Leaving Interpreter, back to program.')
-
-    # Make a second instance, you can have as many as you want.
-    cfg2 = cfg.copy()
-    shell_config = cfg2.InteractiveShellEmbed
-    shell_config.prompt_in1 = 'In2<\\#>: '
-    if not nested:
-        shell_config.prompt_in1 = 'In2<\\#>: '
-        shell_config.prompt_in2 = '   .\\D.: '
-        shell_config.prompt_out = 'Out<\\#>: '
-    ipshell2 = InteractiveShellEmbed(config=cfg,
-                            banner1 = 'Second IPython instance.')
-
-    print '\nHello. This is printed from the main controller program.\n'
-
-    # You can then call ipshell() anywhere you need it (with an optional
-    # message):
-    ipshell('***Called from top level. '
-            'Hit Ctrl-D to exit interpreter and continue program.\n'
-            'Note that if you use %kill_embedded, you can fully deactivate\n'
-            'This embedded instance so it will never turn on again')
-
-    print '\nBack in caller program, moving along...\n'
-
-    #---------------------------------------------------------------------------
-    # More details:
-
-    # InteractiveShellEmbed instances don't print the standard system banner and
-    # messages. The IPython banner (which actually may contain initialization
-    # messages) is available as get_ipython().banner in case you want it.
-
-    # InteractiveShellEmbed instances print the following information everytime they
-    # start:
-
-    # - A global startup banner.
-
-    # - A call-specific header string, which you can use to indicate where in the
-    # execution flow the shell is starting.
-
-    # They also print an exit message every time they exit.
-
-    # Both the startup banner and the exit message default to None, and can be set
-    # either at the instance constructor or at any other time with the
-    # by setting the banner and exit_msg attributes.
-
-    # The shell instance can be also put in 'dummy' mode globally or on a per-call
-    # basis. This gives you fine control for debugging without having to change
-    # code all over the place.
-
-    # The code below illustrates all this.
-
-
-    # This is how the global banner and exit_msg can be reset at any point
-    ipshell.banner = 'Entering interpreter - New Banner'
-    ipshell.exit_msg = 'Leaving interpreter - New exit_msg'
-
-    def foo(m):
-        s = 'spam'
-        ipshell('***In foo(). Try %whos, or print s or m:')
-        print 'foo says m = ',m
-
-    def bar(n):
-        s = 'eggs'
-        ipshell('***In bar(). Try %whos, or print s or n:')
-        print 'bar says n = ',n
-
-    # Some calls to the above functions which will trigger IPython:
-    print 'Main program calling foo("eggs")\n'
-    foo('eggs')
-
-    # The shell can be put in 'dummy' mode where calls to it silently return. This
-    # allows you, for example, to globally turn off debugging for a program with a
-    # single call.
-    ipshell.dummy_mode = True
-    print '\nTrying to call IPython which is now "dummy":'
-    ipshell()
-    print 'Nothing happened...'
-    # The global 'dummy' mode can still be overridden for a single call
-    print '\nOverriding dummy mode manually:'
-    ipshell(dummy=False)
-
-    # Reactivate the IPython shell
-    ipshell.dummy_mode = False
-
-    print 'You can even have multiple embedded instances:'
-    ipshell2()
-
-    print '\nMain program calling bar("spam")\n'
-    bar('spam')
-
-    print 'Main program finished. Bye!'
-
-    #********************** End of file <example-embed.py> ***********************
+.. literalinclude:: ../../examples/core/example-embed.py
+    :language: python
 
 Once you understand how the system functions, you can use the following
 code fragments in your programs which are ready for cut and paste:
 
-.. sourcecode:: python
-
-    """Quick code snippets for embedding IPython into other programs.
-
-    See example-embed.py for full details, this file has the bare minimum code for
-    cut and paste use once you understand how to use the system."""
-
-    #---------------------------------------------------------------------------
-    # This code loads IPython but modifies a few things if it detects it's running
-    # embedded in another IPython session (helps avoid confusion)
-
-    try:
-        get_ipython
-    except NameError:
-        argv = ['']
-        banner = exit_msg = ''
-    else:
-        # Command-line options for IPython (a list like sys.argv)
-        argv = ['-pi1','In <\\#>:','-pi2','   .\\D.:','-po','Out<\\#>:']
-        banner = '*** Nested interpreter ***'
-        exit_msg = '*** Back in main IPython ***'
-
-    # First import the embeddable shell class
-    from IPython.Shell import IPShellEmbed
-    # Now create the IPython shell instance. Put ipshell() anywhere in your code
-    # where you want it to open.
-    ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
-
-    #---------------------------------------------------------------------------
-    # This code will load an embeddable IPython shell always with no changes for
-    # nested embededings.
-
-    from IPython import embed
-    # Now embed() will open IPython anywhere in the code.
-
-    #---------------------------------------------------------------------------
-    # This code loads an embeddable shell only if NOT running inside
-    # IPython. Inside IPython, the embeddable shell variable ipshell is just a
-    # dummy function.
-
-    try:
-        get_ipython
-    except NameError:
-        from IPython.frontend.terminal.embed import embed
-        # Now embed() will open IPython anywhere in the code
-    else:
-        # Define a dummy embed() so the same code doesn't crash inside an
-        # interactive IPython
-        def embed(): pass
-
-    #******************* End of file <example-embed-short.py> ********************
+.. literalinclude:: ../../examples/core/example-embed-short.py
+    :language: python
 
 Using the Python debugger (pdb)
 ===============================
@@ -1492,49 +1306,11 b' This allows you to show a piece of code, run it and then execute'
 interactively commands based on the variables just created. Once you
 want to continue, you simply execute the next block of the demo. The
 following listing shows the markup necessary for dividing a script into
-sections for execution as a demo::
-
-
-    """A simple interactive demo to illustrate the use of IPython's Demo class.
-
-    Any python script can be run as a demo, but that does little more than showing
-    it on-screen, syntax-highlighted in one shot.  If you add a little simple
-    markup, you can stop at specified intervals and return to the ipython prompt,
-    resuming execution later.
-    """
-
-    print 'Hello, welcome to an interactive IPython demo.'
-    print 'Executing this block should require confirmation before proceeding,'
-    print 'unless auto_all has been set to true in the demo object'
-
-    # The mark below defines a block boundary, which is a point where IPython will
-    # stop execution and return to the interactive prompt.
-    # Note that in actual interactive execution, 
-    # <demo> --- stop ---
-
-    x = 1
-    y = 2
-
-    # <demo> --- stop ---
-
-    # the mark below makes this block as silent
-    # <demo> silent
-
-    print 'This is a silent block, which gets executed but not printed.'
-
-    # <demo> --- stop ---
-    # <demo> auto
-    print 'This is an automatic block.'
-    print 'It is executed without asking for confirmation, but printed.'
-    z = x+y
-
-    print 'z=',x
+sections for execution as a demo:
 
-    # <demo> --- stop ---
-    # This is just another normal block.
-    print 'z is now:', z
+.. literalinclude:: ../../examples/lib/example-demo.py
+    :language: python
 
-    print 'bye!'
 
 In order to run a file as a demo, you must first make a Demo object out
 of it. If the file is named myscript.py, the following code will make a