-m yobx run-doc-examples … run all runpython:: and gdot:: examples

The command scans RST documentation files and/or Python source files for .. runpython:: and .. gdot:: directives, executes each embedded code block in an isolated subprocess, and reports which blocks pass and which fail.

Description

See yobx.helpers._check_runpython.extract_runpython_blocks() and yobx.helpers._check_runpython.run_runpython_blocks().

    usage: run-doc-examples [-h] [--ext EXT] [--timeout TIMEOUT] [-v VERBOSE] inputs [inputs ...]
    
    Extracts all ``.. runpython::`` and ``.. gdot::`` code blocks from
    RST documentation files or Python source files (docstrings) and
    executes each one in an isolated subprocess. Exits with a non-zero
    status when at least one block fails.
    
    positional arguments:
      inputs                RST or Python files (or directories) to scan for runpython:: blocks.
    
    options:
      -h, --help            show this help message and exit
      --ext EXT             Comma-separated list of file extensions to include when a directory is given (default: '.rst,.py').
      --timeout TIMEOUT     Per-block execution timeout in seconds (no limit by default).
      -v VERBOSE, --verbose VERBOSE
                            Verbosity level: 0=failures only, 1=each block status, 2=also show code.
    
    examples:
    
        # Check every runpython block in a single RST file
        python -m yobx run-doc-examples docs/design/misc/helpers.rst
    
        # Check all RST files in a directory tree
        python -m yobx run-doc-examples docs/ -v 1
    
        # Check Python source files (docstring examples)
        python -m yobx run-doc-examples yobx/helpers/helper.py -v 2
    
        # Multiple paths at once
        python -m yobx run-doc-examples \
            docs/design/misc/helpers.rst \
            yobx/helpers/helper.py \
            -v 1

Examples

Check all examples in a single RST file:

python -m yobx run-doc-examples docs/design/misc/helpers.rst

Check all RST files inside a directory (recursively):

python -m yobx run-doc-examples docs/ -v 1

Check Python docstring examples in a source file:

python -m yobx run-doc-examples yobx/helpers/helper.py -v 2

Scan several paths at once with a per-block timeout:

python -m yobx run-doc-examples \\
    docs/design/misc/helpers.rst \\
    yobx/helpers/helper.py \\
    --timeout 60 -v 1

Exit code

The command exits with 0 when every block passes (or when no blocks are found), and with 1 when at least one block fails or times out. This makes it easy to use in CI pipelines:

python -m yobx run-doc-examples docs/ || exit 1