module sphinxext.sphinx_runpython_extension

Inheritance diagram of pyquickhelper.sphinxext.sphinx_runpython_extension

Short summary

module pyquickhelper.sphinxext.sphinx_runpython_extension

Defines runpython directives. See Tutorial: Writing a simple extension

New in version 1.2.

source on GitHub

Classes

class truncated documentation
runpython_node defines runpython node source on GitHub
RunPythonCompileError exception raised when a piece of code included in the documentation does not compile source on GitHub
RunPythonDirective extracts script to run described by ``
RunPythonExecutionError exception raised when a piece of code included in the documentation raises en exception source on GitHub

Functions

function truncated documentation
depart_runpython_node What to do when leaving a node runpython_node the function should have different behaviour, depending …
run_python_script Execute a script python as a string.
setup setup for runpython (sphinx) source on GitHub
visit_runpython_node What to do when visiting a node runpython_node the function should have different behaviour, depending …

Methods

method truncated documentation
run extracts the information in a dictionary, run the script

Documentation

Defines runpython directives. See Tutorial: Writing a simple extension

New in version 1.2.

source on GitHub

exception pyquickhelper.sphinxext.sphinx_runpython_extension.RunPythonCompileError[source][source]

Bases: Exception

exception raised when a piece of code included in the documentation does not compile

source on GitHub

class pyquickhelper.sphinxext.sphinx_runpython_extension.RunPythonDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source][source]

Bases: docutils.parsers.rst.Directive

extracts script to run described by .. runpython:: and modifies the documentation

A python script which generates documentation

The following code prints the version of Python on the standard output. It is added to the documentation:

.. runpython::
    :showcode:

    import sys
    print("sys.version_info=", str(sys.version_info))

If give the following results:

    sys.version_info= sys.version_info(major=3, minor=6, micro=2, releaselevel='final', serial=0)

Options showcode can be used to display the code. The option rst will assume the output is in RST format and must be interpreted. showout will complement the RST output with the raw format.

The directive has a couple of options:

  • :indent:<int> to indent the output
  • :showcode: to show the code before its output
  • :rst: to interpret the output, otherwise, it is considered as raw text
  • :sin:<text_for_in> which text to display before the code (by default In)
  • :sout:<text_for_in> which text to display before the output (by default Out)
  • :showout if :rst: is set up, this flag adds the raw rst output to check what is happening
  • :sphinx: by default, function nested_parse_with_titles is used to parse the output of the script, if this option is set to false, public_doctree.
  • :setsysvar: adds a member to sys module, the module can act differently based on that information, if the value is left empty, sys.enable_disabled_documented_pieces_of_code will be be set up to True.
  • :process: run the script in an another process
  • :exception: the code throws an exception but it is expected. The error is displayed.
  • :nopep8: if present, leaves the code as it is and does not apply pep8 by default, see remove_extra_spaces_and_pep8.

Option rst can be used the following way:

.. runpython::
    :rst:

    for l in range(0,10):
        print("**line**", "*" +str(l)+"*")
        print('')

Which displays interpreted RST:

line 0

line 1

line 2

line 3

line 4

line 5

line 6

line 7

line 8

line 9

If the directive produces RST text to be included later in the documentation, it is able to interpret docutils directives and Sphinx directives with function nested_parse_with_titles

Unless process option is enabled, global variables cannot be used.

Changed in version 1.3: Titles, references or label are now allowed.

Changed in version 1.5: Exception is now caught. It fails if no error is thrown. Options nopep8 was added.

source on GitHub

run()[source][source]

extracts the information in a dictionary, run the script

Returns:a list of nodes

source on GitHub

runpython_class[source]

alias of runpython_node

exception pyquickhelper.sphinxext.sphinx_runpython_extension.RunPythonExecutionError[source][source]

Bases: Exception

exception raised when a piece of code included in the documentation raises en exception

source on GitHub

pyquickhelper.sphinxext.sphinx_runpython_extension.depart_runpython_node(self, node)[source][source]

What to do when leaving a node runpython_node the function should have different behaviour, depending on the format, or the setup should specify a different function for each.

source on GitHub

pyquickhelper.sphinxext.sphinx_runpython_extension.run_python_script(script, params=None, comment=None, setsysvar=None, process=False, exception=False)[source][source]

Execute a script python as a string.

Parameters:
  • script – python script
  • params – params to add before the execution
  • comment – message to add in a exception when the script fails
  • setsysvar – if not None, add a member to module sys, set up this variable to True, if is remove after the execution
  • process – run the script in a separate process
  • exception – expects an exception to be raised, fails if it is not, the function returns no output and the error message
Returns:

stdout, stderr

If the execution throws an exception such as NameError: name 'math' is not defined after importing the module math. It comes from the fact the domain name used by the function exec contains the declared objects. Example:

import math
def coordonnees_polaires(x,y):
    rho     = math.sqrt(x*x+y*y)
    theta   = math.atan2 (y,x)
    return rho, theta
coordonnees_polaires(1, 1)

The code can be modified into:

def fake_function():
    import math
    def coordonnees_polaires(x,y):
        rho     = math.sqrt(x*x+y*y)
        theta   = math.atan2 (y,x)
        return rho, theta
    coordonnees_polaires(1, 1)
fake_function()

Changed in version 1.3: Parameters setsysvar, process were added.

Changed in version 1.5: Parameter exception was added.

source on GitHub

class pyquickhelper.sphinxext.sphinx_runpython_extension.runpython_node(rawsource='', *children, **attributes)[source][source]

Bases: docutils.nodes.Structural, docutils.nodes.Element

defines runpython node

source on GitHub

__slotnames__ = [][source]
pyquickhelper.sphinxext.sphinx_runpython_extension.setup(app)[source][source]

setup for runpython (sphinx)

source on GitHub

pyquickhelper.sphinxext.sphinx_runpython_extension.visit_runpython_node(self, node)[source][source]

What to do when visiting a node runpython_node the function should have different behaviour, depending on the format, or the setup should specify a different function for each.

source on GitHub