This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.1.0).
Sphinx directive to support embedded IPython code.
This directive allows pasting of entire interactive IPython sessions, prompts and all, and their code will actually get re-executed at doc build time, with all prompts renumbered sequentially. It also allows you to input code as a pure python input by giving the argument python to the directive. The output looks like an interactive ipython section.
To enable this directive, simply list it in your Sphinx conf.py file (making sure the directory where you placed it is visible to sphinx, as is needed for all Sphinx directives).
By default this directive assumes that your prompts are unchanged IPython ones, but this can be customized. The configurable options that can be placed in conf.py are
An embedded IPython instance to run inside Sphinx
process block from the block_parser and return a list of processed lines
Process data fPblock for COMMENT token.
# build out an image directive like # .. image:: somefile.png # :width 4in # # from an input like # savefig somefile.png width=4in
Process data block for INPUT token.
process the input, capturing stdout
Process data block for OUTPUT token.
content is a list of strings. it is unedited directive conent
This runs it line by line in the InteractiveShell, prepends prompts as needed capturing stderr and stdout, then returns the content as a list as if it were ipython code
Saves the image file to disk.
part is a string of ipython text, comprised of at most one input, one ouput, comments, and blank lines. The block parser parses the text into a list of:
blocks = [ (TOKEN0, data0), (TOKEN1, data1), ...]
where TOKEN is one of [COMMENT | INPUT | OUTPUT ] and data is, depending on the type of token:
COMMENT : the comment string INPUT: the (DECORATOR, INPUT_LINE, REST) where DECORATOR: the input decorator (or None) INPUT_LINE: the input as string (possibly multi-line) REST : any stdout generated by the input line (not OUTPUT) OUTPUT: the output string, possibly multi-line