Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン
  • 何か問題がありますか？
#159 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
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日 20時間
マージ済み PR（30日）
34

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

petercorke/machinevision-toolbox-python のほかの issue

petercorke/machinevision-toolbox-python の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。