Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

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

未关闭
  • 哪里不对？
#159 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
39/100
Issue 类型
缺陷
描述清晰度
描述清楚
活跃度
活跃
技术栈
python
领域
documentation, testing

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

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.

主要语言
Python
星标
224
派生
35
平均合并
1 天 22 小时
30 天内合并 PR
29

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

petercorke/machinevision-toolbox-python 的其他 Issue

查看 petercorke/machinevision-toolbox-python 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。