document-public-apis

パブリック API をドキュメント化する

このスキルでは、docs/source/conf.py のカバレッジ除外リストから項目を削除し、対応する docs/source/ 内の .md または .rst ドキュメントソースファイルに Sphinx autodoc ディレクティブ（例：autosummary、currentmodule、autoclass、automodule）を追加して、PyTorch の未ドキュメント化のパブリック API をドキュメント化します。

「ドキュメント化」とは、ドキュメントソースファイルに autodoc ディレクティブを追加することです。Python ソースコードは絶対に変更しないでください。 .py ファイルの docstring を追加または編集しないでください。正しいドキュメントファイルに正しいディレクティブを追加することだけが、あなたの役割です。

重要：関数を sphinx doctree に追加する前に、実際の docstring があることを確認してください。 簡単な Python チェック（例：python -c "from torch.module import func; print(bool(func.__doc__))"）を使い、空の docstring や .. warning:: This API is experimental だけのスタブではなく、実際のドキュメント内容があることを確認してください。意味のある docstring がない関数は、coverage_ignore_functions／coverage_ignore_classes リストに残してください。ドキュメント化されていない関数を doctree に追加すると、空またはほぼ空のページが生成され、ドキュメントの品質が低下します。

概要

docs/source/conf.py には、ドキュメント化されていない API に関する Sphinx のカバレッジ警告を抑制するリストが 2 つあります。

• coverage_ignore_functions：ドキュメント化されていない関数
• coverage_ignore_classes：ドキュメント化されていないクラス

項目はモジュールコメントのグループごとに整理されています。各グループにはモジュールラベルコメントがあり、その後に該当するモジュールに属する関数名／クラス名が続きます。

coverage_ignore_functions = [
    # torch.ao.quantization.fx.convert              <-- module label comment
    "convert",                                       # <-- entries belonging to this module
    "convert_custom_module",
    "convert_standalone_module",
    "convert_weighted_module",
    # torch.ao.quantization.fx.fuse                 <-- next module group
    "fuse",
    # torch.nn.functional
    "assert_int_or_pair",  # looks unintentionally public   <-- entry with inline comment
    "constant",  # deprecated                                <-- entry with inline comment
]

コメントには 2 種類あります。

• モジュールラベルコメント（# torch.ao.quantization.fx.convert）：その下の項目がどのモジュールに属するかを示します。項目グループの前の独立した行にあります。
• インラインコメント（# deprecated、# documented as adaptive_max_pool1d）：文字列項目と同じ行にあり、その項目が除外リストに含まれている理由を説明します。

モジュールラベルコメントから、次のことが直接わかります。

1. 関数が属するモジュール
2. ドキュメント内で追加する場所（例：# torch.ao.quantization.fx.convert → 関数はドキュメントファイルの torch.ao.quantization.fx.convert の下に追加します）

手順

このスキルの各実行では、モジュールグループを1 バッチ処理します。除外リストから 1 つ以上の完全なモジュールグループを選び、その関数をドキュメント化して検証してください。

ステップ 1：ドキュメント化するモジュールグループを選択する

docs/source/conf.py を読み、ドキュメント化する完全なモジュールグループを 1 つ以上選択します。モジュールグループとは、モジュールラベルコメントと、その下から次のモジュールラベルコメントまでにあるすべての項目を指します。グループ全体を処理してください。1 つのグループを複数のバッチに分割してはいけません。

たとえば、torch.ao.quantization.fx.convert グループを選択する場合、次の項目をすべて対象にします。

# torch.ao.quantization.fx.convert
"convert",
"convert_custom_module",
"convert_standalone_module",
"convert_weighted_module",

リストを上から順に処理してください。意味のある進捗が得られるよう、十分な数のグループを選びます（関数の合計が 5～15 個になることを目安とします。ただし、少し超える場合でも必ずグループ全体を含めてください）。

項目を含める前に、インラインコメントを確認してください。 ドキュメント化しないことを示すインラインコメントが付いた項目もあります。

• # deprecated — 関数は非推奨です。除外リストに残してください。
• # documented as <other_name> — すでに別の名前でドキュメント化されています。そのまま残してください。
• # looks unintentionally public — パブリック API として意図されていない可能性があります。そのまま残してください。
• # legacy helper for ... — 非推奨と同様です。そのまま残してください。
• # utility function — そのまま残してください。

モジュールグループに通常の項目とインラインコメント付きの項目が混在している場合でも、グループ全体を処理します。ただし、除外リストでコメントアウトするのは通常の項目だけです。インラインコメント付きの項目には手を加えず、そのまま除外リストに残してください。

ステップ 1b：関数に実際の docstring があることを確認する

ステップ 1 で選択した関数ごとに、次のコマンドを実行して、意味のある docstring があることを確認します。

python -c "from torch.module.path import func_name; doc = func_name.__doc__; print('HAS DOC' if doc and len(doc.strip()) > 80 else 'NO DOC'); print(repr(doc[:120]) if doc else 'None')"

次のような内容だけではなく、実際の説明が含まれている場合、その関数には意味のある docstringがあります。

• None または空文字列
• 説明のない .. warning:: This API is experimental のスタブだけ
• 自動生成された署名の 1 行だけ

意味のある docstring がない関数は、ignore リストに残す必要があります。 バッチから削除してください。モジュールグループ全体に docstring がある関数がなければ、そのグループ全体をスキップしてください。

ステップ 2：バッチをユーザーに提示する

編集を行う前に、選択したモジュールグループとその関数をユーザーに提示します。docstring チェックに合格した関数と、除外された関数を示してください。モジュールごとに整理して表示します。

Module: torch.ao.quantization.fx.convert
  - convert
  - convert_custom_module
  - convert_standalone_module
  - convert_weighted_module

Module: torch.ao.quantization.fx.fuse
  - fuse

次に AskUserQuestion ツールを使って、以下のような選択肢を提示し、ユーザーに確認します。

• 「このバッチを実行する」
• 「一部の項目をスキップする」（ユーザーが削除する項目を指定できます）
• 「別のバッチを選ぶ」

ステップ 3：conf.py の項目をコメントアウトする

ユーザーの確認後、docs/source/conf.py を編集し、選択した項目を削除せずにコメントアウトします。各文字列の項目行に # を付けます。

# torch.ao.quantization.fx.convert
# "convert",
# "convert_custom_module",
# "convert_standalone_module",
# "convert_weighted_module",

これにより元の項目が保持され、検証に失敗した場合に復元できます。

ステップ 4：Sphinx coverage を実行する

cd docs && make coverage

make coverage のターミナル出力は無視してください。Sphinx 拡張機能（例：onnx_ir、katex、sphinxcontrib）に起因する無関係なトレースバックやエラーが含まれることがよくあります。重要なのは、docs/build/coverage/python.txt が生成されたかどうかだけです。そのファイルを読み、具体的にどの API がドキュメント化されていないかを確認してください。

python.txt には、ドキュメント化されていない API が次の形式で一覧表示されます。

torch.ao.quantization.fx.convert
   * convert
   * convert_custom_module
   * convert_standalone_module
   * convert_weighted_module

コメントアウトした関数がすべて python.txt に表示されるとは限りません。 すでに別の場所でドキュメント化されている場合があります。問題ありません。python.txt に実際に表示される関数に対してのみ、ディレクティブを追加してください。

依存関係が不足していて make coverage が失敗する場合は、まず次を実行します。

cd docs && pip install -r requirements.txt

ステップ 5：ドキュメントディレクティブを追加する

python.txt に記載された関数ごとに、追加先を判断するため、conf.py のモジュールラベルのコメントを参照します。モジュールコメントには完全なモジュールパスが記載されており、それによってドキュメントソースファイルと、そのファイル内のセクションが分かります。

正しいドキュメントファイルを見つける

モジュールコメントから docs/source/ 内のドキュメントソースファイルを特定します。判断に迷った場合は、同じモジュール内の他の関数を検索してください。

grep -rn "torch.module_name" docs/source/*.md docs/source/*.rst

または、候補ファイルを一覧表示します。

ls docs/source/*module_name*

サブモジュールのドキュメントファイルがない場合は、親モジュールのドキュメントファイルにそのサブモジュールのセクションがあるか確認します（例：backends.md には torch.backends.cuda、torch.backends.cudnn などのセクションがあります）。なければ、既存のパターンに従って親ファイルに新しいセクションを追加します。

ディレクティブの追加

まず対象のドキュメントファイルを読み、そこで既に使われている正確なパターンに合わせてください。新しいパターンを考案したり、完全修飾名で裸の autofunction を使ったりしないでください。常に automodule、currentmodule、短い名前を使った適切な階層構造を使用してください。. py:module:: は使わないでください。これはエラーを抑制するだけで、実際に関数をドキュメント化しないからです。docs/source/ 配下にある、対象ファイルと同じ形式 (例: .md と .rst) の他のファイルを見て、例を確認してください。

ファイル形式は 2 つあります。対象ファイルで使われている方に合わせてください。

パターン A — MyST Markdown ファイル (.md): accelerator.md、backends.md、cuda.md などのファイルで使われています。

階層構造では、automodule でモジュールを登録し、currentmodule でコンテキストを設定してから、短い名前を使います:

## torch.ao.quantization.fx.convert

```{eval-rst}
.. automodule:: torch.ao.quantization.fx.convert

.. currentmodule:: torch.ao.quantization.fx.convert

.. autofunction:: convert

.. autofunction:: convert_custom_module

For `autosummary` blocks (used in some files instead of individual directives):

```markdown
```{eval-rst}
.. autosummary::
    :toctree: generated
    :nosignatures:

    existing_function
    your_new_function
`` `

クラスの場合:

```{eval-rst}
.. autoclass:: YourClass
    :members:
`` `

パターン B — reStructuredText ファイル (.rst): torch.rst、nn.rst などのファイルで使われています。

Markdown のフェンスがないだけで、同じ階層構造です:

torch.ao.quantization.fx.convert
---------------------------------

.. automodule:: torch.ao.quantization.fx.convert

.. currentmodule:: torch.ao.quantization.fx.convert

.. autosummary::
    :toctree: generated
    :nosignatures:

    convert
    convert_custom_module
    convert_standalone_module
    convert_weighted_module

個別のディレクティブの場合:

.. automodule:: torch.submodule

.. currentmodule:: torch.submodule

.. autofunction:: function_name

.. autoclass:: ClassName
    :members:

重要なルール:

• conf.py のモジュールラベルコメント (例: # torch.ao.quantization.fx.convert) は、どの automodule と currentmodule を使うべきかを正確に示しています。
• モジュールの関数をドキュメント化する前に、必ず .. automodule:: と .. currentmodule:: を設定してください。
• currentmodule を設定した後は、短い名前 (例: torch.ao.quantization.fx.convert.convert ではなく convert) を使用してください。
• ファイル内のモジュールに既に automodule/currentmodule がある場合は、別のものを追加しないでください — 既存のものの下に自分の関数を追加するだけです。
• ファイルが既に使っているスタイル (autosummary ブロックか個別の autofunction ディレクティブか) に合わせてください。

適切なセクションへの配置

対象のドキュメントファイルを読み、適切なセクションを見つけてください。モジュールに既にセクションがある場合 (例: backends.md の ## torch.backends.cuda)、そこに関数を追加してください。まだセクションが存在しない場合は、ファイル内の既存のセクションパターンに従って作成してください。同じモジュールグループの関数はすべてまとめてグループ化してください。

ステップ 6: カバレッジで検証する

カバレッジを再度実行します:

cd docs && make coverage

ターミナル出力は無視してください — docs/build/coverage/python.txt だけを読んでください。検証は、python.txt に 全モジュールにわたって未ドキュメントの関数がゼロ であれば合格です。すべてのモジュールについて、100% のカバレッジと未ドキュメント数 0 の統計テーブルのみが含まれているはずです。例えば:

Undocumented Python objects
===========================

Statistics
----------

+---------------------------+----------+--------------+
| Module                    | Coverage | Undocumented |
+===========================+==========+==============+
| torch                     | 100.00%  | 0            |
+---------------------------+----------+--------------+
| torch.accelerator         | 100.00%  | 0            |
+---------------------------+----------+--------------+

いずれかのモジュールに未ドキュメントの関数が表示されている場合 (カバレッジが 100% 未満、または未ドキュメント数が 0 より大きい)、検証は失敗です。

検証が成功した場合 (全モジュールで未ドキュメントがゼロ): ステップ 7 に進んでください。

検証が失敗した場合 (未ドキュメントの関数が残っている): docs/build/coverage/python.txt を読み、どの関数がまだ未ドキュメントとしてリストされているかを確認してください。よくある問題は次のとおりです:

• 間違ったドキュメントファイル: 関数が間違った .md/.rst ファイルに追加されています。ディレクティブを正しいファイルに移動してください。
• 間違ったディレクティブの種類: 例えば、クラスに autofunction を使ったり、関数に autoclass を使ったりしています。ディレクティブを修正してください。
• ディレクティブ内の間違ったモジュールパス: 例えば、torch.foo.bar は torch.foo.baz.bar であるべきです。修飾名を修正してください。
• 間違った currentmodule を持つ autosummary ブロックに関数が追加されている: ブロックの上の .. currentmodule:: ディレクティブが一致していることを確認してください。
• まだ登録されていないサブモジュールの automodule が欠落している。そのサブモジュールの関数をドキュメント化する前に、.. automodule:: torch.submodule ディレクティブを追加してください。

エラーに基づいてドキュメントディレクティブを修正し、再度 make coverage を実行してください。検証が合格するまで繰り返してください。

複数回試しても関数が失敗し続ける場合は、停止してユーザーにエラーを表示してください。 関数名とエラーを提示し、次のようなオプションを付けて AskUserQuestion ツールを使用してください:

• 「コメントを解除して無視リストに戻す (今はスキップ)」
• 「別のアプローチを試す」
• 「さらに調査する」

Step 7: 進捗を報告する

次の内容を示す進捗の概要をユーザーに提示します。

• 処理したモジュールグループと、ドキュメント化した関数の数
• スキップした関数、または ignore リストに戻した関数（およびその理由）
• coverage_ignore_functions と coverage_ignore_classes に残っているエントリ数

Step 8: conf.py 内のコメントアウトされたエントリを整理する

検証に合格したら、Step 3 でコメントアウトした文字列エントリを削除します。対象は、coverage_ignore_functions と coverage_ignore_classes 内で # " から始まる行です。コメントアウトされた文字列エントリには必ず引用符が含まれているため、モジュールラベルのコメントと区別できます。

# "disable_global_flags",       <-- commented-out string entry (has quotes) → DELETE
# torch.backends                <-- module label comment (no quotes) → KEEP if it has active entries

また、アクティブなエントリが下に残っていないモジュールラベルのコメントも削除します（つまり、そのモジュールのエントリがすべてコメントアウトされて削除された場合、またはインラインコメントが付いているためそのまま残されたものの、モジュールラベルの下に他のエントリがない場合）。

重要な注意事項

• 手順に書かれたとおりに正確に進めてください。 make coverage の実行は Sphinx ディレクティブが正しいことを確認するための主要な検証であり、Step 1b の docstring チェックにより、実際に内容がある関数だけをドキュメント化できます。
• Python ソースファイル（.py）は絶対に変更しないでください。 このスキルで編集するのは docs/source/conf.py と docs/source/ 内のドキュメントソースファイル（.md／.rst）のみです。docstring を追加・編集してはいけません。Python モジュールを調べるのは、Step 1b で docstring が存在するか確認する場合に限ります。ソースコードは決して変更しないでください。
• エントリは Step 3 でコメントアウトし、Step 6 で検証し、検証に合格した後の Step 8 で整理します。コメントアウトされていないエントリを直接削除してはいけません。
• ドキュメント化するか判断する前に、エントリのインラインコメントを読んでください。# deprecated、# documented as ...、# looks unintentionally public、# legacy helper と記されたエントリは ignore リストに残してください。
• coverage_ignore_functions リストには完全修飾名ではなく関数名だけが使われるため、異なるモジュールに同じ名前が複数回登場する場合があります。各エントリの上にあるモジュールラベルのコメントを使って、どのモジュールに属するかを特定してください。Step 8 で整理するときは、正しいコメントアウト行だけを削除するよう注意してください。コメントアウトされた文字列エントリには引用符（# "func_name",）がありますが、モジュールラベルのコメントにはありません。
• 対象のドキュメントファイルの既存のスタイルに必ず合わせてください。.rst ファイルに .md のスタイルのディレクティブを混在させたり、その逆をしたりしないでください。
• automodule／currentmodule ディレクティブと、ドキュメントファイル内の適切なセクションを特定する際は、モジュールラベルのコメント（例：# torch.ao.quantization.fx.convert）を必ず主な手がかりにしてください。
• 常にモジュールグループを最後まで処理してください。1 つのグループを複数回の実行に分割してはいけません。