sphinx-pyrunblock 1.0.0__tar.gz

sphinx_pyrunblock-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.tox
+*.pyc
+.eggs
+build
+dist
+*.egg-info
+.claude
+.DS_Store

sphinx_pyrunblock-1.0.0/AUTHORS

@@ -0,0 +1,4 @@
+Peter Corke <rvc@petercorke.com>
+Hugo Osvaldo Barrera <hugo@barrera.io>
+Michael McNeil Forbes <mforbes@physics.ubc.ca>
+Vadim Gubergrits <vadim@outboxtechnology.com>

sphinx_pyrunblock-1.0.0/LICENCE

@@ -0,0 +1,26 @@
+Copyright (c) 2020-2026, Peter Corke.
+Copyright (c) 2009-2017, The Contributors (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sphinx_pyrunblock-1.0.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: sphinx-pyrunblock
+Version: 1.0.0
+Summary: Sphinx extension that executes code and embeds real output in docs (.. runblock:: directive)
+Project-URL: Homepage, https://github.com/petercorke/sphinx-pyrunblock
+Project-URL: Bug Tracker, https://github.com/petercorke/sphinx-pyrunblock/issues
+Project-URL: Documentation, https://petercorke.github.io/sphinx-pyrunblock
+Project-URL: GitHub Source, https://github.com/petercorke/sphinx-pyrunblock
+Project-URL: Changelog, https://github.com/petercorke/sphinx-pyrunblock/blob/main/CHANGELOG.md
+Author-email: Peter Corke <rvc@petercorke.com>, Hugo Osvaldo Barrera <hugo@barrera.io>
+License-Expression: BSD-2-Clause
+License-File: LICENCE
+Keywords: doctest,documentation,runblock,sphinx
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: sphinx>=4.0
+Provides-Extra: dev
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="https://github.com/petercorke/sphinx-pyrunblock/raw/main/docs/figs/pyrunblock-logo.svg" width="350">
+  <br><br>
+
+[![PyPI version](https://img.shields.io/pypi/v/sphinx-pyrunblock?style=for-the-badge&color=blue)](https://pypi.org/project/sphinx-pyrunblock/)
+  [![Documentation](https://img.shields.io/badge/Docs-View_Online-blue?style=for-the-badge)](https://petercorke.github.io/sphinx-pyrunblock/)
+  [![Build Status](https://img.shields.io/github/actions/workflow/status/petercorke/sphinx-pyrunblock/ci.yml?branch=main&style=for-the-badge)](https://github.com/petercorke/sphinx-pyrunblock/actions/workflows/ci.yml)
+</div>
+
+# sphinx-pyrunblock
+
+Fast, in-process embedding of live Python code output into your Sphinx docs.
+`sphinx-pyrunblock` runs each `.. runblock::` example directly in a shared
+interpreter rather than spawning a subprocess per block — and it's backward
+compatible with `sphinx-autorun`: same `runblock` directive, same
+`autorun_languages` config shape, drop-in upgrade.
+
+```rst
+    .. runblock:: pycon
+
+        >>> for i in range(5):
+        ...    print(i)
+```
+
+Produces:
+
+```
+    >>> for i in range(5):
+    ...    print(i)
+    0
+    1
+    2
+    3
+    4
+```
+
+## Installation
+
+```
+    $ pip install sphinx-pyrunblock
+```
+
+Enable the extension by adding it to the `extensions` list in `conf.py`:
+
+```python
+    extensions.append("sphinx_pyrunblock")
+```
+
+See the [full documentation](https://petercorke.github.io/sphinx-pyrunblock/)
+for configuration (`conf.py` options, `runfirst` setup), per-block directive
+options (`:numpy:`, `:scipy:`, `:smtb:`, `:precision:`, `:include:`,
+`:exclude:`), and how errors are reported during a build.
+
+## Heritage
+
+`sphinx-pyrunblock` began as a fork of
+[sphinx-autorun](https://github.com/WhyNotHugo/sphinx-autorun) by Hugo
+Osvaldo Barrera, itself descended from Vadim Gubergrits' original
+`sphinxcontrib-autorun`. See the
+[full history](https://petercorke.github.io/sphinx-pyrunblock/about.html)
+for the complete lineage.

sphinx_pyrunblock-1.0.0/README.md

@@ -0,0 +1,61 @@
+<div align="center">
+  <img src="https://github.com/petercorke/sphinx-pyrunblock/raw/main/docs/figs/pyrunblock-logo.svg" width="350">
+  <br><br>
+
+[![PyPI version](https://img.shields.io/pypi/v/sphinx-pyrunblock?style=for-the-badge&color=blue)](https://pypi.org/project/sphinx-pyrunblock/)
+  [![Documentation](https://img.shields.io/badge/Docs-View_Online-blue?style=for-the-badge)](https://petercorke.github.io/sphinx-pyrunblock/)
+  [![Build Status](https://img.shields.io/github/actions/workflow/status/petercorke/sphinx-pyrunblock/ci.yml?branch=main&style=for-the-badge)](https://github.com/petercorke/sphinx-pyrunblock/actions/workflows/ci.yml)
+</div>
+
+# sphinx-pyrunblock
+
+Fast, in-process embedding of live Python code output into your Sphinx docs.
+`sphinx-pyrunblock` runs each `.. runblock::` example directly in a shared
+interpreter rather than spawning a subprocess per block — and it's backward
+compatible with `sphinx-autorun`: same `runblock` directive, same
+`autorun_languages` config shape, drop-in upgrade.
+
+```rst
+    .. runblock:: pycon
+
+        >>> for i in range(5):
+        ...    print(i)
+```
+
+Produces:
+
+```
+    >>> for i in range(5):
+    ...    print(i)
+    0
+    1
+    2
+    3
+    4
+```
+
+## Installation
+
+```
+    $ pip install sphinx-pyrunblock
+```
+
+Enable the extension by adding it to the `extensions` list in `conf.py`:
+
+```python
+    extensions.append("sphinx_pyrunblock")
+```
+
+See the [full documentation](https://petercorke.github.io/sphinx-pyrunblock/)
+for configuration (`conf.py` options, `runfirst` setup), per-block directive
+options (`:numpy:`, `:scipy:`, `:smtb:`, `:precision:`, `:include:`,
+`:exclude:`), and how errors are reported during a build.
+
+## Heritage
+
+`sphinx-pyrunblock` began as a fork of
+[sphinx-autorun](https://github.com/WhyNotHugo/sphinx-autorun) by Hugo
+Osvaldo Barrera, itself descended from Vadim Gubergrits' original
+`sphinxcontrib-autorun`. See the
+[full history](https://petercorke.github.io/sphinx-pyrunblock/about.html)
+for the complete lineage.

sphinx_pyrunblock-1.0.0/docs/figs/pyrunblock-logo.svg

@@ -0,0 +1,15 @@
+<svg width="500" height="120" xmlns="http://www.w3.org/2000/svg">
+  <!-- Document Outline -->
+  <path d="M30 20 h 30 l 20 20 v 60 h -50 Z" fill="none" stroke="#2C3E50" stroke-width="4" stroke-linejoin="round"/>
+  <path d="M60 20 v 20 h 20" fill="none" stroke="#2C3E50" stroke-width="4" stroke-linejoin="round"/>
+  
+  <!-- Terminal Bottom Half -->
+  <rect x="20" y="60" width="70" height="45" rx="4" fill="#2C3E50" />
+  
+  <!-- Terminal Prompt -->
+  <text x="30" y="90" font-family="monospace" font-size="18" fill="#FFB300" font-weight="bold">&gt;_</text>
+  
+  <!-- Typography Header -->
+  <text x="110" y="80" font-family="sans-serif" font-size="36" fill="#2C3E50" font-weight="800" letter-spacing="-1">sphinx-</text>
+  <text x="245" y="80" font-family="monospace" font-size="36" fill="#FFB300" font-weight="bold">pyrunblock</text>
+</svg>

sphinx_pyrunblock-1.0.0/docs/source/about.rst

@@ -0,0 +1,68 @@
+About this project
+====================
+
+``sphinx-pyrunblock`` is a hard fork of `sphinx-autorun
+<https://github.com/WhyNotHugo/sphinx-autorun>`_ by Hugo Osvaldo Barrera,
+itself several generations descended from the original
+``sphinxcontrib-autorun`` by Vadim Gubergrits. Full acknowledgement of
+that lineage lives on this page; :file:`LICENCE` and :file:`AUTHORS` in
+the repository root carry the legal/contributor record.
+
+Lineage
+-------
+
+Oldest to newest, verified against this repository's own git history
+where the line passes directly through it (marked *verified* below), and
+from research at the time of the 2026 rename otherwise:
+
+- **sphinxcontrib-autorun** (Vadim Gubergrits, starting 2010-03-04
+  *(verified: first commit* ``1b76446``\ *)*, hosted on the old
+  Bitbucket-based ``sphinx-contrib`` collection). Michael McNeil Forbes
+  contributed to this original project too (*verified*: commit
+  ``be1cbd3``, 2012-11-19).
+- **sphinxcontrib-autorun2** (David Wolever, 2014) -- a parallel fork
+  published under a new name rather than a continuation; sphinx-contrib
+  forks were commonly released this way rather than via commit rights to
+  the original. Not part of this project's direct line.
+- **sphinx-autorun-ng** (Hugo Osvaldo Barrera, 2017) -- dropped the
+  ``sphinxcontrib`` namespace, moved off Bitbucket. Released once, then
+  immediately renamed.
+- **sphinx-autorun** (same Hugo Osvaldo Barrera, 2017 onward, i.e.
+  ``WhyNotHugo`` on GitHub *(verified: this repository's own git history
+  contains Hugo's "Fork into sphinx_autorun" commit,* ``dc9c315``\ *,
+  2017-01-10)* -- this is the project still actively maintained today,
+  and the one the ``sphinx-autorun`` name on PyPI resolves to.
+- A separate one-off side-branch, **sphinx-autorun-ebs** (Endre Bakken
+  Stovner, 2018, one release), also exists but was never touched again
+  and isn't part of this line.
+- **sphinx-pyrunblock** (Peter Corke) -- this project. Forked from
+  ``WhyNotHugo/sphinx-autorun`` 2020-10-26 *(verified: first commit*
+  ``2549daa``, *"Eliminate the line buffering error"*\ *)*. The fix was
+  also submitted upstream the same day, as `PR #19
+  <https://github.com/WhyNotHugo/sphinx-autorun/pull/19>`_ -- it sat open
+  for over four years and was eventually closed 2025-01-02 in favour of
+  `PR #65 <https://github.com/WhyNotHugo/sphinx-autorun/pull/65>`_, a
+  different, simpler fix for the same underlying bug submitted by another
+  contributor and merged that same day.
+
+  No further commits landed in this fork until a rewrite arrived
+  2025-01-12, replacing the original subprocess-per-block execution with
+  a single, shared, in-process interpreter -- the change this project's
+  speed comes from. That rewrite was motivated by real docs-build time
+  becoming a pain point during the push to ship Robotics Toolbox for
+  Python and Machine Vision Toolbox for Python, both of which use this
+  extension to execute live code examples during their own documentation
+  builds.
+
+Why a hard fork
+----------------
+
+``sphinx-autorun`` was never published to PyPI under that name from this
+line of descent -- ``sphinx-autorun`` on PyPI is, and remains, Hugo
+Osvaldo Barrera's actively-maintained project. Publishing this project's
+own substantially rewritten execution engine under an unrelated,
+already-claimed name wasn't viable, hence the rename to
+``sphinx-pyrunblock`` and a clean detachment from the GitHub fork
+network it started in. The directive name (``.. runblock::``) is
+unchanged, and existing ``conf.py`` ``autorun_languages`` configuration
+carries over -- only the package/import name differs.

sphinx_pyrunblock-1.0.0/docs/source/conf.py

@@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+
+from sphinx_pyrunblock import __version__
+
+project = "sphinx-pyrunblock"
+copyright = "2020-2026, Peter Corke"
+author = "Peter Corke"
+release = __version__
+version = __version__
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx_pyrunblock",
+    "sphinx.ext.autosectionlabel",
+]
+autosectionlabel_prefix_document = True
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+# -- sphinx-pyrunblock setup --------------------------------------------------
+# Python session setup shared by every runblock example on this site: turn
+# off SE3/ANSITable colour codes (they don't render usefully as plain HTML
+# text) and fix numpy's print precision so output is stable across builds.
+autorun_languages = {}
+autorun_languages[
+    "pycon_runfirst"
+] = """
+from spatialmath import SE3
+SE3._color = False
+import numpy as np
+np.set_printoptions(precision=4, suppress=True)
+from ansitable import ANSITable
+ANSITable._color = False
+"""
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

sphinx_pyrunblock-1.0.0/docs/source/configuration.rst

@@ -0,0 +1,100 @@
+Configuration
+=============
+
+``sphinx-pyrunblock`` is configured through a single ``conf.py`` dict,
+``autorun_languages``. This page is the complete reference for it. For
+options that apply to one ``runblock`` directive invocation rather than
+the whole document, see :ref:`per-block options <index:Per-block options>`.
+
+The ``autorun_languages`` dict
+-------------------------------
+
+.. code-block:: python
+
+    autorun_languages = {}
+    autorun_languages["pycon_runfirst"] = "..."
+
+The dict's keys are **not** language names in the usual sense -- ``pycon``
+is really the only supported language, a historical artifact of an earlier
+design that also executed a ``console`` (bash) language via a separate
+subprocess. That's no longer how this extension works: every block runs
+in a single, shared, in-process ``code.InteractiveInterpreter``, which is
+what makes it fast (no subprocess spawned per code block). Think of
+``pycon`` as the key *prefix* under which each of the settings below is
+namespaced, rather than a literal interpreter selection.
+
+At Sphinx's ``builder-inited`` event, whatever you set in
+``autorun_languages`` is merged on top of the extension's own defaults
+(``pycon``, ``pycon_prefix_chars``, ``pycon_show_source``). You only need
+to set the keys you want to change.
+
+Per-language keys
+------------------
+
+``<lang>``
+    Declares ``<lang>`` a valid argument to the ``runblock`` directive
+    (e.g. ``.. runblock:: pycon`` requires ``"pycon"`` to be a key in the
+    merged config). The *value* itself is vestigial -- it dates from the
+    old subprocess-per-language design, where it was the shell command to
+    pipe code into. It isn't read for anything today; only the key's
+    presence matters.
+
+``<lang>_prefix_chars``
+    Number of characters to strip from the start of each prompted line
+    (``>>>`` or ``...``, plus the following space) before executing it.
+    Defaults to ``0`` if unset; the built-in ``pycon`` default is ``4``,
+    matching the length of ``"``>>> ``"``.
+
+``<lang>_show_source``
+    If true, echo each line of source to the Sphinx build log as it runs
+    (useful when debugging a block that isn't producing the output you
+    expect). Defaults to ``False``.
+
+``<lang>_runfirst``
+    A newline-separated string of Python statements, **without prompts**,
+    executed once before every ``runblock:: <lang>`` block in the
+    document, in the same shared interpreter session. Doesn't appear in
+    the rendered output. This is the main per-project customisation
+    point -- typically used to import commonly-used modules and set up
+    formatting/print options once, rather than repeating it in every
+    example.
+
+A full worked example
+-----------------------
+
+This is the actual ``pycon_runfirst`` used to build this documentation
+(also representative of what Peter's other toolboxes use): it silences
+colour-code output from two libraries that would otherwise embed raw
+ANSI escapes in the HTML, and fixes numpy's print precision so output is
+stable across builds.
+
+.. code-block:: python
+
+    autorun_languages = {}
+    autorun_languages[
+        "pycon_runfirst"
+    ] = """
+    from spatialmath import SE3
+    SE3._color = False
+    import numpy as np
+    np.set_printoptions(precision=4, suppress=True)
+    from ansitable import ANSITable
+    ANSITable._color = False
+    """
+
+Gotchas
+-------
+
+- The directive's ``:numpy:``/``:scipy:`` options (see
+  :ref:`per-block options <index:Per-block options>`) layer **on top of**
+  ``<lang>_runfirst`` -- they don't replace it. ``<lang>_runfirst`` always
+  runs first, then any per-block imports requested via directive options.
+- ``:precision: N`` calls ``np.set_printoptions``, so numpy must already
+  be imported by that point -- either via ``:numpy:`` on the same
+  directive, or because ``<lang>_runfirst`` already imports it.
+- ``<lang>_prefix_chars`` only strips characters from lines that actually
+  start with a prompt (``>>>`` or ``...``, plus the following space). A
+  bare continuation line (for example, the body of a triple-quoted string
+  spanning several lines) is
+  left untouched, so multi-line string literals in your examples render
+  correctly.

sphinx_pyrunblock-1.0.0/docs/source/index.rst

@@ -0,0 +1,175 @@
+sphinx-pyrunblock
+==================
+
+.. image:: ../figs/pyrunblock-logo.svg
+   :align: center
+   :width: 350
+   :alt: sphinx-pyrunblock
+
+``sphinx-pyrunblock`` is a Sphinx extension that executes code from a
+``runblock`` directive and inserts the real output into your documentation.
+For example::
+
+    .. runblock:: pycon
+
+        >>> for i in range(5):
+        ...    print(i)
+
+produces:
+
+.. runblock:: pycon
+
+    >>> for i in range(5):
+    ...    print(i)
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   configuration
+   about
+
+Installation
+------------
+
+.. code-block:: console
+
+    $ pip install sphinx-pyrunblock
+
+Enable the extension by adding it to the ``extensions`` list in ``conf.py``:
+
+.. code-block:: python
+
+    extensions = [
+        "sphinx_pyrunblock",
+    ]
+
+See :doc:`configuration` for the full ``conf.py`` reference.
+
+Worked examples
+----------------
+
+.. runblock:: pycon
+
+   >>> from spatialmath.base import trnorm, troty
+   >>> from numpy import linalg
+   >>> T = troty(45, 'deg', t=[3, 4, 5])
+   >>> linalg.det(T[:3,:3]) - 1 # is a valid SO(3)
+   >>> T = T @ T @ T @ T @ T @ T @ T @ T @ T @ T @ T @ T @ T
+   >>> linalg.det(T[:3,:3]) - 1  # not quite a valid SE(3) anymore
+   >>> T = trnorm(T)
+   >>> linalg.det(T[:3,:3]) - 1  # once more a valid SE(3)
+
+.. runblock:: pycon
+
+   >>> from spatialmath.base import qconj, qprint
+   >>> q = [1, 2, 3, 4]
+   >>> qprint(qconj(q))
+
+Per-block options
+------------------
+
+Options are given on the directive itself, and apply to that one block only
+(compare :doc:`configuration` for options that apply document-wide, via
+``conf.py``):
+
+``:linenos:``
+    Show line numbers in the rendered code block.
+
+``:include: start-end``
+    Only render lines in the given range of the block's *output* (line
+    numbers count the block's own statements, not the configured
+    ``runfirst`` code, which never appears in output).
+
+``:exclude: start-end``
+    Skip lines in the given range, same numbering as ``:include:``.
+
+``:numpy:``
+    Prepend ``import numpy as np`` before the block runs.
+
+``:scipy:``
+    Prepend ``import scipy as sp`` before the block runs.
+
+``:smtb:``
+    Append ``from spatialmath import *`` before the block runs.
+
+``:precision: N``
+    Append ``np.set_printoptions(precision=N)`` before the block runs.
+    Requires numpy to already be imported (via ``:numpy:`` or a configured
+    ``runfirst`` -- see :doc:`configuration`).
+
+.. runblock:: pycon
+   :include:  5-10
+
+      >>> from spatialmath.base import getunit
+      >>> import numpy as np
+      >>> getunit(1.5, 'rad')
+      >>> getunit(90, 'deg')
+      >>> getunit(90, 'deg', vector=False) # force a scalar output
+      >>> getunit(1.5, 'rad', dim=0) # check argument is scalar
+      >>> getunit(1.5, 'rad', dim=3) # check argument is a 3-vector
+      >>> getunit([1.5], 'rad', dim=1) # check argument is a 1-vector
+      >>> getunit([1.5], 'rad', dim=3) # check argument is a 3-vector
+      >>> getunit(90, 'deg')
+      >>> getunit([90, 180], 'deg')
+      >>> getunit(np.r_[0.5, 1], 'rad')
+      >>> getunit(np.r_[90, 180], 'deg')
+      >>> getunit(np.r_[90, 180], 'deg', dim=2)
+      >>> getunit([90, 180, 270], 'deg', dim=3)
+
+For any construct with an indented body (``for``, ``while``, ``with``), it's
+important to put a blank line on the end. That will be stripped off and
+won't appear in the output.
+
+.. runblock:: pycon
+   :numpy:
+
+   >>> from spatialmath.base import getunit
+   >>> getunit(1.5, 'rad')
+   >>> try:
+   >>>   getunit(1.5, 'rad', dim=0)
+   >>> except Exception as e:
+   >>>   print(f"EXCEPTION {e}")
+   >>>
+   >>> for i in range(5):
+   >>>    print(i)
+   >>>
+
+Lines ending with ``# ignore`` are executed but not shown in the rendered
+output -- useful for setup code that would otherwise clutter the example.
+
+Error reporting
+----------------
+
+If the code raises an exception, a diagnostic marker is written to the
+Sphinx build log and a short error summary is embedded in the rendered
+output:
+
+.. code-block:: text
+
+    >>> img.metadata('FocalLength')
+    !! [RUNBLOCK-ERROR] machinevisiontoolbox/ImageIO.py:236
+        KeyError: 'FocalLength'
+
+The build log entry is more detailed:
+
+.. code-block:: text
+
+    !! [RUNBLOCK-ERROR] source/numpy.rst:98
+        ModuleNotFoundError: No module named 'machinevisionToolbox'
+        Traceback (most recent call last):
+          File "<input>", line 1, in <module>
+        ModuleNotFoundError: No module named 'machinevisionToolbox'
+
+The marker line appears **before** the traceback so failures are easy to
+scan in a long build log. The source location (``file:line``) refers to the
+``.rst`` file, or the Python source file containing the docstring where the
+``runblock`` directive lives.
+
+A syntax error in the code block is reported the same way:
+
+.. code-block:: text
+
+    >>> print(("Hello, world")
+    !! [RUNBLOCK-ERROR] source/api.rst:42
+        SyntaxError: '(' was never closed

sphinx_pyrunblock-1.0.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+
+authors = [
+    { name = "Peter Corke", email = "rvc@petercorke.com" },
+    { name = "Hugo Osvaldo Barrera", email = "hugo@barrera.io" },
+]
+name = "sphinx-pyrunblock"
+version = "1.0.0"
+description = "Sphinx extension that executes code and embeds real output in docs (.. runblock:: directive)"
+
+readme = "README.md"
+license = "BSD-2-Clause"
+license-files = ["LICENCE"]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    # Indicate who your project is intended for
+    "Intended Audience :: Developers",
+    # Specify the Python versions you support here.
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+
+    "Operating System :: OS Independent",
+]
+keywords = ["sphinx", "documentation", "doctest", "runblock"]
+
+dependencies = ["Sphinx>=4.0"]
+
+[project.urls]
+
+"Homepage" = "https://github.com/petercorke/sphinx-pyrunblock"
+"Bug Tracker" = "https://github.com/petercorke/sphinx-pyrunblock/issues"
+"Documentation" = "https://petercorke.github.io/sphinx-pyrunblock"
+"GitHub Source" = "https://github.com/petercorke/sphinx-pyrunblock"
+"Changelog" = "https://github.com/petercorke/sphinx-pyrunblock/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest", "coverage", "ruff"]
+
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "--tb=short"
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sphinx_pyrunblock"]
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_pyrunblock"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/test", "/tests", "/.git", "/.github", "/.claude", "/.vscode"]
+
+[tool.black]
+line-length = 88
+target-version = ["py39", "py310", "py311", "py312", "py313"]
+
+[tool.coverage.run]
+omit = []