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). For example, to enable syntax highlighting and the IPython directive:
extensions = ['IPython.sphinxext.ipython_console_highlighting', 'IPython.sphinxext.ipython_directive']
The IPython directive outputs code-blocks with the language ‘ipython’. So if you do not have the syntax highlighting extension enabled as well, then all rendered code-blocks will be uncolored. 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:
As an example, to use the IPython directive when matplotlib is not available, one sets the backend to None:
ipython_mplbackend = None
An example usage of the directive is:
.. ipython:: In : x = 1 In : y = x**2 In : print(y)
See http://matplotlib.org/sampledoc/ipython_directive.html for additional documentation.
Note: Only one decorator is supported per input. If more than one decorator is specified, then only the last one is used.
In addition to the Pseudo-Decorators/options described at the above link, several enhancements have been made. The directive will emit a message to the console at build-time if code-execution resulted in an exception or warning. You can suppress these on a per-block basis by specifying the :okexcept: or :okwarning: options:
.. ipython:: :okexcept: :okwarning: In : 1/0 In : # raise warning.
An embedded IPython instance to run inside Sphinx
Perform a specialized doctest.
Ensures that pyplot has been imported into the embedded IPython shell.
Also, makes sure to set the backend appropriately if not set already.
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 content
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