From fa42ce728cf1e5f24ed8150cb410b163c9aa24d5 2011-06-30 17:16:44 From: MinRK Date: 2011-06-30 17:16:44 Subject: [PATCH] use `literalinclude` to embed examples in reference doc also moved 'demo' examples into lib, since that's where demo is. --- diff --git a/docs/examples/core/demo-exercizer.py b/docs/examples/core/demo-exercizer.py deleted file mode 100644 index 4085a03..0000000 --- a/docs/examples/core/demo-exercizer.py +++ /dev/null @@ -1,85 +0,0 @@ -"""This is meant to be run from the IPython prompt: - -%run demo-exercizer.py - -It will create demo objects of the example that is embedded in demo.py in a -number of ways and allow you to see how they work, just follow the printed -directions.""" - -#----------------------------------------------------------------------------- -# Imports -#----------------------------------------------------------------------------- - -# From std lib -import StringIO -import os -import shutil -import tempfile - -# From IPython -from IPython.demo import (Demo, IPythonDemo, LineDemo, IPythonLineDemo, - ClearDemo, ClearIPDemo) - -#----------------------------------------------------------------------------- -# Demo code -#----------------------------------------------------------------------------- - -example1 = """ -'''A simple interactive demo to illustrate the use of IPython's Demo class.''' - -print 'Hello, welcome to an interactive IPython demo.' - -# The mark below defines a block boundary, which is a point where IPython will -# stop execution and return to the interactive prompt. The dashes are actually -# optional and used only as a visual aid to clearly separate blocks while -# editing the demo code. -# stop - -x = 1 -y = 2 - -# stop - -# the mark below makes this block as silent -# silent - -print 'This is a silent block, which gets executed but not printed.' - -# stop -# auto -print 'This is an automatic block.' -print 'It is executed without asking for confirmation, but printed.' -z = x+y - -print 'z=',x - -# stop -# This is just another normal block. -print 'z is now:', z - -print 'bye!' -""" -fp = tempfile.mkdtemp(prefix = 'DemoTmp') -fd, filename = tempfile.mkstemp(prefix = 'demoExample1File', suffix = '.py', - dir = fp) -f = os.fdopen(fd, 'wt') - -f.write(example1) -f.close() - -my_d = Demo(filename) -my_cd = ClearDemo(filename) - -fobj = StringIO.StringIO(example1) -str_d = Demo(fobj, title='via stringio') - -print ''' -The example that is embeded in demo.py file has been used to create -the following 3 demos, and should now be available to use: - my_d() -- created from a file - my_cd() -- created from a file, a ClearDemo - str_d() -- same as above, but created via a StringIO object -Call by typing their name, (with parentheses), at the -ipython prompt, interact with the block, then call again -to run the next block. -''' diff --git a/docs/examples/core/example-demo.py b/docs/examples/core/example-demo.py deleted file mode 100644 index 3bfd6b1..0000000 --- a/docs/examples/core/example-demo.py +++ /dev/null @@ -1,40 +0,0 @@ -"""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, -# --- stop --- - -x = 1 -y = 2 - -# --- stop --- - -# the mark below makes this block as silent -# silent - -print 'This is a silent block, which gets executed but not printed.' - -# --- stop --- -# auto -print 'This is an automatic block.' -print 'It is executed without asking for confirmation, but printed.' -z = x+y - -print 'z=',z - -# --- stop --- -# This is just another normal block. -print 'z is now:', z - -print 'bye!' diff --git a/docs/examples/core/example-embed-short.py b/docs/examples/core/example-embed-short.py index cc5824d..09bd449 100644 --- a/docs/examples/core/example-embed-short.py +++ b/docs/examples/core/example-embed-short.py @@ -25,9 +25,6 @@ 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. diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt index c7898f2..14bece3 100644 --- a/docs/source/interactive/reference.txt +++ b/docs/source/interactive/reference.txt @@ -1022,200 +1022,14 @@ 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 *********************** +.. 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 ******************** +.. literalinclude:: ../../examples/core/example-embed-short.py + :language: python Using the Python debugger (pdb) =============================== @@ -1492,49 +1306,11 @@ 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, - # --- stop --- - - x = 1 - y = 2 - - # --- stop --- - - # the mark below makes this block as silent - # silent - - print 'This is a silent block, which gets executed but not printed.' - - # --- stop --- - # 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: - # --- 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