Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#159 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
39/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python
Ambito
documentation, testing

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Python
Stelle
224
Fork
31
Merge medio
1g 22h
PR unite (30g)
29

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di petercorke/machinevision-toolbox-python

Tutte le issue di petercorke/machinevision-toolbox-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.