Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#159 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
39/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
python
Área
documentation, testing

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
224
Forks
35
Merge medio
1 d 20 h
PR fusionados (30 d)
34

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de petercorke/machinevision-toolbox-python

Todos los issues de petercorke/machinevision-toolbox-python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.