Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

Docs build succeeds with broken examples: fix 7 failing runblock examples and fail the build on errors

Offen
  • Stimmt etwas nicht?
#159 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
39/100
Issue-Typ
Bug
Klarheit
Klar beschrieben
Aktivitätsstatus
Aktiv
Tech-Stack
python
Bereich
documentation, testing

Rechercherichtung

Start by running sphinx-build -b html docs/source docs/build/html and searching its output for RUNBLOCK-ERROR; the issue names examples in ImageBlobs.py, ImageCore.py, ImageIO.py, ImageFiducials.py, ImageTensor.Tensor, and source/tensor.rst. Read each listed example and its implementation, checking the available mvtbdata image and the documented PyTorch build setup. Done when the listed examples work or are non-executed where needed, and enabling pycon_fail_on_error makes the docs build fail on a runblock error.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

tech-debt

sphinx-pyrunblock executes the .. runblock:: pycon examples in docstrings and .rst pages at build time. When an example raises, it prints a !! [RUNBLOCK-ERROR] <file>:docstring of <object>:<line> block to the terminal, but that is not a Sphinx warning. The build still ends with build succeeded and exit code 0, so broken examples (with their tracebacks in the rendered output) ship unnoticed.

Found on origin/main at 77a3da9c (2026-10-17), both in CI's Docs Publish job (23 error lines) and in a local sphinx-build -b html docs/source docs/build/html in a clean venv (19 lines; Sphinx 9.1.0, sphinx-pyrunblock 1.2.0, OpenCV 5.0.0.93). To find them, grep the build output for RUNBLOCK-ERROR.

Examples to fix

  • Blobs.vc (ImageBlobs.py, example around line 822): blobs.v does not exist (AttributeError). Typo or stale attribute name.
  • Image.A (ImageCore.py, around line 2140): the example does img.A = np.zeros((50,50)), but Image is now immutable and .A is deprecated (since 2.0.0), so it raises. Rewrite to show creating a new Image.
  • Image.array_as (ImageCore.py:2346-2347): calls img.array_int(...), which no longer exists; use array_as.
  • Image.showwindow (ImageIO.py, around line 498): the signature is showwindow(self, h, ax, **kwargs) but the example calls showwindow(h=1) without ax, then uses an undefined window. Fix the example or the signature.
  • Image.fiducial (ImageFiducials.py:115): reads tags.png, which is not in mvtbdata; apriltag12.png is. Use an image that exists (and make sure the dictionary name matches the tags in it).
  • ImageTensor.Tensor and source/tensor.rst (lines 30 and 47): PyTorch is not installed in the docs build (ModuleNotFoundError, ImportError: PyTorch is required). Either add torch (CPU wheel) to the docs extra, or turn these into non-executed code blocks.
  • Image.draw_point (ImageCore.py:4169): fails on OpenCV 5.0; this is a library bug, tracked in #158, not an example error.

Most of the NameErrors in the logs (img, tensor, fiducials, window, W, rand) are fallout from one of the above failing earlier in the same block.

Stop it regressing

  • Turn on sphinx-pyrunblock's pycon_fail_on_error (added in 1.1.0) once the list above is clean, so a failing example fails the docs build. Until then, consider a CI step that greps the build log for RUNBLOCK-ERROR and prints the count.

This should be resolved before the next release; the Docs Publish job currently publishes these tracebacks.

Related: the 111 ordinary Sphinx warnings in the same build (9 "Block quote ends without a blank line", cross-reference ambiguities, duplicate object descriptions, the SMTB intersphinx 404) are a separate clean-up.

Vorherrschende Sprache
Python
Sterne
224
Forks
31
Ø Merge
1 T. 22 Std.
Gemergte PRs (30 T.)
29

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus petercorke/machinevision-toolbox-python

Alle Issues in petercorke/machinevision-toolbox-python

Ähnliche Issues

Weitere Issues zu Python

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.