開発版ドキュメント · 0.2.3 30c2f8ba · 入門例の検証対象 0.2.3 · 版情報 · 既知の制限

検証と品質の見方#

このページでは、gwexpy が現在どの種類の検証シグナルを公開しているか、その根拠がどこにあるか、そしてその限界をどう読むべきかを整理します。

ここで示すのは「すべての機能が一様に検証済み」という主張ではありません。Notebook、direct I/O、アルゴリズム監査、ドキュメントビルドについて、それぞれ別の根拠に辿れるようにするための案内ページです。

重要

このページは「透明性の地図」であって、一括保証ではありません

検証の方法は対象ごとに異なります。extended verification workflow は、手動実行時にクロスプラットフォームのインポートスモークテストと対象を絞ったゲート（ネットワーク/バックエンド I/O、docs ノートブック、Zarr I/O）を実行します。Notebook の中には CI で全実行されるものもあれば、重い notebook のように構造確認中心のものもあり、optional dependency を持つテストは環境によって skip される場合もあります。

公開されている根拠の入口#

対象

公開資料

何がわかるか

Notebook チュートリアル

ノートブックポリシー

Light / Heavy / Display-only の分類と、CI がそれぞれをどう扱うか

拡張検証ゲート

拡張検証ワークフロー

extended verification workflow（手動実行）が対象とするチェック：Linux/macOS/Windows でのインポートスモークテストに加え、scripts/ci/run_gate.py が駆動する io-network-backend・docs-notebook・io-zarr ゲート

direct I/O 形式

SUPPORTED_IO_MATRIX

どの公開 format 群に、どのテストファイルが対応づけられているかと、どこに optional backend があるか

アルゴリズム監査

検証済みアルゴリズム

数値許容誤差、前提条件、監査証跡へのリンク

Notebook の検証方針#

公開 notebook の扱いは、リポジトリ内の Notebook Policy に基づきます。

旧ドキュメントの Notebook 方針と、刷新後 Web サイトのビルド経路は分かれています。

  • 旧ドキュメントツリーはリポジトリの Notebook Policy に従います。Light、Heavy、Display-only の分類は、Papermill と nbval の確認を含む従来の Notebook 検証制度を示します。

  • 刷新後 Web サイトは、隔離した一時コピーから EN と JA の HTML をビルドします。実行結果が必要な場合、MyST-NB はクリーンな Notebook ソースをビルドキャッシュで実行します。キャッシュとレンダリング済み出力は公開用アーティファクトであり、追跡対象の .ipynb ファイルを変更しません。

  • 刷新後サイトの PR、プレビュー、production のワークフローは、同じ隔離ビルド経路を使用します。これらは一般の Docs PR ワークフローにある旧ドキュメントの検査とは別です。

現時点の公開方針は次のとおりです。

  • 公開されている extended verification workflow は、クロスプラットフォームのインポートスモークテストと io-network-backend・docs-notebook・io-zarr ゲートを実行します。意図的にこれらのチェックへ範囲を絞っており、docstring の doctest は実行しません。

  • Light、Heavy、Display-only は旧方針の分類です。旧 Notebook の実行状況を判断する前に、その方針を確認してください。

  • 刷新後 Web サイトは、隔離した一時コピーから行う EN と JA の Sphinx ビルドで検証されます。レンダリング済み Notebook 出力は MyST-NB キャッシュで生成され、Git にはコミットされません。

  • 手動実行の extended verification ワークフローは、対象を絞った独立の検査です。すべてのドキュメント例をリリースゲートにするものではありません。

したがって、「公開 docs に notebook や例がある」こと自体は有益なシグナルですが、それだけで「あらゆる PR / Nightly / release 経路で毎回一律に実行・保証される」とまでは読まない方が安全です。

現在の CI カバレッジとその限界#

現在の公開根拠から言えるのは、「すべてのサンプルコードが一律に保証される」よりも狭い範囲です。

  • extended verification workflow が示すように、gwexpy はワークフロー実行時に、3 つのプラットフォームでのインポートスモークテストに加え、I/O と docs ノートブックのゲートを自動実行します。

  • Notebook Policy が示すように、notebook の扱いは分類依存で、Light は papermill で実行、Heavy は nbval --nbval-lax で確認されます。

  • 刷新後サイトのビルドは、隔離した一時コピー内でのみ Notebook ソースを実行し、結果を MyST-NB キャッシュに保持します。

このシグナルは次のように読んでください。

  • 公開例が管理されていないわけではありません。刷新後サイトのビルドと旧 Notebook 方針は、異なる範囲を検証します。

  • ただし、すべての公開コード片が、すべての workflow で毎回実行されることを意味しません。

  • Doctest や notebook 検証が、ドキュメント全体に対する単一の release-blocking gate だという意味でもありません。

  • 強い保証として読む前に、notebook の分類、optional dependency、どの workflow がその対象を見ているかを確認する必要があります。

direct I/O の検証可視化#

public direct I/O の検証可視化では、SUPPORTED_IO_MATRIX が主要な入口です。

この表は、たとえば次のような疑問に答えるときに使います。

  • 「この format は公開対応としてどこまで見てよいか」

  • 「この format claim はどのテストファイルに紐づいているか」

  • 「この経路は optional backend に依存するのか」

ファイル I/O 対応フォーマットガイド と合わせて読むと、特に役割分担が明確になります：

  • user guide 側は「どう選ぶか」「どう呼ぶか」を説明し、

  • matrix 側は「どのテストが根拠か」を示し、

  • 備考が optional dependency や skip 条件を補います。

自動テストの根拠を読む#

上記の公開資料は、自動テストとドキュメントビルドの根拠を確認するための現在の入口です。慎重に読み取ってください。

  • 特定の公開上の主張を、どの workflow またはテストスイートが扱うかを確認できます。

  • they do not prove that every algorithm branch, notebook, or optional-backend path is equally exercised,

  • and they should be read alongside page-specific evidence such as the notebook policy, I/O matrix, and audit notes.

このページが主張しないこと#

  • すべての公開 notebook が、すべての CI 実行で全セル再実行されるとは主張しません。

  • すべての docstring 例やサンプルコード片が、すべての PR / Nightly / release workflow で毎回実行されるとは主張しません。

  • すべての optional dependency が、すべての test 環境に入っているとは主張しません。

  • 検証済みアルゴリズム に書かれた個別の前提条件や許容誤差を、このページが置き換えるものではありません。

  • 集計されたテスト結果を、そのまま feature 単位の科学的妥当性の証明に読み替えるべきだとは主張しません。

次に読む#