[tarotene]

No-Issue: /github-audit-triage の drift 修正で、対応する Issue は無い

課題

このリポジトリは Python のパッケージ(lab)だが、API ドキュメントを strict にビルドする検査が CI に無く、docstring・型注釈の誤りが検出されない。dotfiles の docs-python アクション(スタック標準の docs 必須化)を呼ぶ job が必要。

解決策

• ci.yml に docs(name: API docs)を足し、ci-passed の needs に加える。既存 job の name: は変えない。requires-python が >=3.13,<3.14 なので、python-version: '3.13' を渡す(既定の 3.x は最新を選び、pip install -e . が落ちる)。
• 手元で同じ手順を実行して出た警告 6 件を、同じ PR で直す。
  • src/lab/parts.py: モジュール docstring 1 行目の build(**params) が rst の強調の開始とみなされていた(Inline strong start-string without end-string)。literal(二重バッククォート)にした。
  • src/lab/check.py: from __future__ import annotations を外した。これがあると dataclass Report の署名の型注釈が文字列になり、tuple[float, float, float] などがカンマで割られて 2 件の警告になっていた。Python 3.13 固定で、実行時にも型注釈の評価で困る箇所は無い(テスト 36 件通過)。
  • build123d.topology.shape_core.Shape の未解決参照 3 件: build123d の公式ドキュメントの目録は build123d. を付けない名前(topology.shape_core.Shape)で持っており、intersphinx では結べない。docs/conf.py を新設して nitpick_ignore に 1 件だけ入れた。
• docs/conf.py を置くとアクションは最小構成の生成をやめてそれを使うため、docs/index.rst(automodule で 5 モジュール)も足した。conf.py はアクションが生成する構成(autodoc・viewcode・doctest・intersphinx・doctest_global_setup)と同じ内容にしてある。docs/ の既存の Markdown は Sphinx の対象外。

Before / After

# Before(docs-python と同じ手順を手元で実行)
build finished with problems, 6 warnings (with warnings treated as errors).
  lab/parts.py:docstring of lab.parts:1: WARNING: Inline strong start-string without end-string.
  <unknown>:1: WARNING: py:class reference target not found: 'tuple[float
  <unknown>:1: WARNING: py:class reference target not found: 'list[tuple[int
  <unknown>:1: WARNING: py:class reference target not found: build123d.topology.shape_core.Shape  (x3)

# After
build succeeded.
(doctest) 0 failures in tests / setup code / cleanup code

検証

手元(uv venv、Python 3.13、docs-python/requirements.txt の Sphinx 9.1.0 と pip install -e .)で実行した。

• 修正前: アクションと同じ最小構成(sphinx-apidoc --full --ext-doctest と、アクションが追記する doctest_global_setup・intersphinx の 2 行)で sphinx-build -W -n -b html を実行し、警告 6 件(上記)を再現した。
• 修正後: docs/conf.py を使う経路で sphinx-build -W -n -b html docs と sphinx-build -W -b doctest docs がともに成功した。
• uv run ruff check .、uv run ruff format --check .、uv run pytest -q(36 passed)、uv run lab check --all が通る。
• PR の CI(API docs job を含む)の結果は、作成後に gh pr checks で確認する。

🤖 Generated with Claude Code