atelier.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 += ['atelier.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.

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

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

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

Bases: docutils.parsers.rst.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 atelier.sphinxconf.insert_input.Py2rstDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: atelier.sphinxconf.insert_input.InsertInputDirective

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.