rstgen.sphinxconf.insert_input¶

Defines the InsertInputDirective class and some subclasses, installing the py2rst directive.

To use it, you must run:

$ pip install atelier

and then add this module to your conf.py:

extensions += ['rstgen.sphinxconf.insert_input']

.. 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.

Warning: installing this extension makes your Sphinx instance unsecure. That is, you should not use this in an environment where arbitrary content can be posted, since that content is actually being executed with the permissions of the process that runs the Sphinx builder.

Functions

setup(app)

Classes

`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.

class rstgen.sphinxconf.insert_input.InsertInputDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)¶

Bases: Directive

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 rstgen.sphinxconf.insert_input.Py2rstDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)¶

Bases: InsertInputDirective

Implements the py2rst directive.

shell_block(cmd)¶

Run the given command and insert a code-block directive that 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.