module sphinxext.sphinx_runpython_extension
¶
Short summary¶
module pyquickhelper.sphinxext.sphinx_runpython_extension
Defines runpython directives. See Tutorial: Writing a simple extension
Classes¶
class |
truncated documentation |
---|---|
Defines runpython node. |
|
exception raised when a piece of code included in the documentation does not compile |
|
Extracts script to run described by `` |
|
Exception raised when a piece of code included in the documentation raises an exception. |
Functions¶
function |
truncated documentation |
---|---|
What to do when leaving a node |
|
Executes a script python as a string. |
|
setup for |
|
What to do when visiting a node |
Properties¶
property |
truncated documentation |
---|---|
|
Return the document root node of the tree containing this Node. |
Methods¶
method |
truncated documentation |
---|---|
Takes the script as a string and returns another string before it is run. It does not modify what is displayed. … |
|
Extracts the information in a dictionary, runs the script. |
Documentation¶
Defines runpython directives. See Tutorial: Writing a simple extension
- exception pyquickhelper.sphinxext.sphinx_runpython_extension.RunPythonCompileError[source]¶
Bases:
Exception
exception raised when a piece of code included in the documentation does not compile
- class pyquickhelper.sphinxext.sphinx_runpython_extension.RunPythonDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶
Bases:
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=9, micro=1, 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:
:assert:
condition to validate at the end of the execution to check it went right:current:
runs the script in the source file directory:exception:
the code throws an exception but it is expected. The error is displayed.:indent:<int>
to indent the output:language:
: changes::
into.. code-block:: language
:linenos:
to show line numbers:nopep8:
if present, leaves the code as it is and does not apply pep8 by default, seeremove_extra_spaces_and_pep8
.:numpy_precision: <precision>
, runnumpy.set_printoptions(precision=...)
, precision is 3 by default:process:
run the script in an another process:restore:
restore the local context stored in sphinx application by the previous call to runpython:rst:
to interpret the output, otherwise, it is considered as raw text: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.:showcode:
to show the code before its output:showout
if :rst: is set up, this flag adds the raw rst output to check what is happening: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):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.:store:
stores the local context in sphinx application to restore it later by another call to runpython:toggle:
add a button to hide or show the code, it takes the valuescode
orout
orboth
. The direction then hides the given section but adds a button to show it.:warningout:
name of warnings to disable (ex:ImportWarning
), separated by spaces:store_in_file:
the directive store the script in a file,then executes this file (only if
:process:
is enabled), this trick is needed when the script to executes relies on function such inspect.getsource which requires the script to be stored somewhere in order to retrieve it.
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. However, if this text contains titles, it is better to use option
:sphinx: false
. Unless process option is enabled, global variables cannot be used. sphinx-autorun offers a similar service except it cannot produce compile RST content, hide the source and a couple of other options. Option toggle can hide or unhide the piece of code or/and its output. The directive also adds local variables such as__WD__
which contains the path to the documentation which contains the directive. It is useful to load additional filesos.path.join(__WD__, ...)
.<<<
print("Hide or unhide this output.")
- modify_script_before_running(script)[source]¶
Takes the script as a string and returns another string before it is run. It does not modify what is displayed. The function can be overwritten by any class based on this one.
- option_spec = {'assert': <function unchanged>, 'current': <function unchanged>, 'exception': <function unchanged>, 'indent': <function unchanged>, 'language': <function unchanged>, 'linenos': <function unchanged>, 'nopep8': <function unchanged>, 'numpy_precision': <function unchanged>, 'process': <function unchanged>, 'restore': <function unchanged>, 'rst': <function unchanged>, 'setsysvar': <function unchanged>, 'showcode': <function unchanged>, 'showout': <function unchanged>, 'sin': <function unchanged>, 'sout': <function unchanged>, 'sout2': <function unchanged>, 'sphinx': <function unchanged>, 'store': <function unchanged>, 'store_in_file': <function unchanged>, 'toggle': <function unchanged>, 'warningout': <function unchanged>}[source]¶
Mapping of option names to validator functions.
- runpython_class[source]¶
alias of
runpython_node
- exception pyquickhelper.sphinxext.sphinx_runpython_extension.RunPythonExecutionError[source]¶
Bases:
Exception
Exception raised when a piece of code included in the documentation raises an exception.
- pyquickhelper.sphinxext.sphinx_runpython_extension.depart_runpython_node(self, node)[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.
- pyquickhelper.sphinxext.sphinx_runpython_extension.run_python_script(script, params=None, comment=None, setsysvar=None, process=False, exception=False, warningout=None, chdir=None, context=None, store_in_file=None)[source]¶
Executes 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
warningout – warning to disable (name of warnings)
chdir – change directory before running this script (if not None)
context – if not None, added to the local context
store_in_file – stores the script into this file and calls tells python the source can be found here, that is useful is the script is using module
inspect
to retrieve the source which are not stored in memory
- Returns:
stdout, stderr, context
If the execution throws an exception such as
NameError: name 'math' is not defined
after importing the modulemath
. 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()
Section l-image-rst-runpython explains how to display an image with this directive.
- class pyquickhelper.sphinxext.sphinx_runpython_extension.runpython_node(rawsource='', *children, **attributes)[source]¶
Bases:
Structural
,Element
Defines runpython node.
- pyquickhelper.sphinxext.sphinx_runpython_extension.visit_runpython_node(self, node)[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.