atelier.sphinxconf.insert_input

(This module’s source code is available here.)

Defines the InsertInputDirective class and some subclasses, installing the following directives:

.. py2rst::

Executes the Python code, capturing the stdout and inserting it to the document, parsing it as reStructuredText.

For example, if you write:

.. py2rst::

    url = 'http://planet.python.org/'
    print("`This <%s>`_ is my *favourite* planet." % url)

then you get:

This is my favourite planet.

Note that when the Sphinx builder is running under Python 2.7, the following future imports have been done:

from __future__ import print_function
from __future__ import unicode_literals

Functions

nested_parse_with_titles(state, content, node) Version of state.nested_parse() that allows titles and does not require titles to have the same decoration as the calling document.
setup(app)

Classes

Directive(name, arguments, options, content, ...) Base class for reStructuredText directives.
InsertInputDirective(name, arguments, ...) Base class for directives that work by generating rst markup to be forwarded to state_machine.insert_input().
Py2rstDirective(name, arguments, options, ...) Implements the py2rst directive.
StringIO([buf]) class StringIO([buffer])
class atelier.sphinxconf.insert_input.InsertInputDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Base class for directives that work by generating rst markup to be forwarded to state_machine.insert_input().

get_rst()

Override this to return a string in rst syntax

class atelier.sphinxconf.insert_input.Py2rstDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Implements the py2rst directive.

shell_block(cmd)

Run the given command and insert a code-block directive which displays both the command and its output.

For example, if your .rst document contains:

.. py2rst::

    self.shell_block(["echo", "Hello", "world!"])

Then it will be rendered as:

$ echo Hello world!
Hello world!

This uses the subprocess.check_output method and the security warnings apply.

If the command returns with a non-zero exit code, the exception is catched and converted into a warning.