check_sphinx_api_html.py 技術ドキュメント

プログラムの動作

check_sphinx_api_html.py は、Sphinx で生成されたAPIドキュメントHTMLファイル（通常 *_api.html という命名規則）を走査し、Sphinx の autodoc 機能がAPI要素を適切に抽出しなかったために、本文コンテンツが空っぽに近いページを検出するスクリプトです。

このプログラムの主な機能は以下の通りです。

  1. HTMLファイルの走査: 指定されたルートディレクトリ以下にある、指定されたワイルドカードパターン（デフォルトは *_api.html）に一致するすべてのHTMLファイルを再帰的に検索します。

  2. メインコンテンツの抽出: 各HTMLファイルから、role="main" や class="document" など、Sphinx が生成する典型的なHTML構造に基づいて主要なコンテンツ領域を抽出します。

  3. テキストのクリーンアップ: 抽出したHTMLコンテンツから、<script>, <style>, <nav>, <footer>, <header> などの不要なタグとその内容を除去し、さらにすべてのHTMLタグを除去してプレーンテキストに変換します。HTMLエンティティのデコードと複数の空白の正規化も行います。

  4. API取り込み失敗の判定: クリーンアップされたテキストの長さ、およびHTML内にSphinx の autodoc が生成する典型的なAPIマーカー（例: py function, py class, sig-name など）の存在をチェックします。本文が極端に短い、またはAPIマーカーが見つからない場合、そのページはAPI取り込みに失敗したと判断します。

  5. 結果の出力: 失敗と判断されたファイルのパスとその理由をコンソールに表示し、指定された出力ファイル（デフォルトは failed_api_html.txt）に失敗したファイルのパスを一覧として書き込みます。

このプログラムは、ドキュメント生成プロセスにおける autodoc の設定ミスや、ソースコードの問題によりAPIドキュメントが不完全に生成される課題を早期に発見し、不完全なドキュメントが公開されるのを防ぐのに役立ちます。

原理

check_sphinx_api_html.py は、Sphinx が autodoc を使って生成したAPIドキュメントのHTML構造と内容の特性を利用して、API定義の取り込みが失敗しているページを識別します。主な原理は以下のコンポーネントに基づいています。

  1. 文字コード推定によるHTML読み込み (read_text 関数) HTMLファイルはさまざまな文字コードで保存されている可能性があるため、この関数は utf-8, cp932 (Shift_JIS-2004), shift_jis, latin-1 の順に文字コードを試行してファイルを読み込みます。これにより、多言語環境や異なる環境で生成されたHTMLファイルにも対応できるようになっています。すべての試行が失敗した場合は、バイト列を utf-8 でエラーを置き換えてデコードします。

  2. メインコンテンツ領域の抽出 (extract_main_html 関数) Sphinx や ReadTheDocs テーマで生成されたHTMLは、ページの主要なコンテンツが特定のHTML要素（例: div with role="main", div with class="document", <section>, <main>, <article> など）で囲まれる傾向があります。この関数は複数の正規表現パターンを順に試し、これらの主要なコンテンツ領域を特定して抽出します。これにより、サイドバー、ヘッダー、フッターなどの補助的な内容を分析から除外します。

  3. HTMLタグの除去とテキストクリーンアップ (strip_html 関数) 抽出されたHTMLコンテンツから、以下のステップでプレーンテキストを生成します。

    • <script>, <style>, <nav>, <footer>, <header> タグとその内容を正規表現で完全に除去します。これらはページの構造や表示に関わるが、APIの内容とは無関係な情報です。

    • 残りのすべてのHTMLタグ (<[^>]+>) を正規表現で除去し、プレーンテキストに変換します。

    • html モジュールの unescape 関数を使用して、&amp;, &lt; などのHTMLエンティティをデコードします。

    • 複数の空白文字 (\s+) を単一の空白に正規化し、文字列の前後の空白を除去 (strip) します。これにより、本文の正確な長さを測定しやすくなります。

  4. API取り込み失敗の判定基準 (check_api_html 関数) この関数が、実際にAPI取り込みの失敗を判断する中心的なロジックを含んでいます。

    • APIマーカーのチェック: Sphinx の autodoc が生成するHTMLには、API要素（関数、クラス、メソッドなど）を示す特定の文字列やHTML属性（例: "py function", "py class", "sig-name", "descname", dl class="py") が含まれます。これらのマーカーがHTML中に存在するかをカウントします。

    • Python APIシグネチャ風の要素のチェック: <dt> タグで class 属性に sig を含む要素（re.findall(r"<dt[^>]*class=[\"'][^\"']*sig[^\"']*[\"'][^>]*>", html, flags=re.IGNORECASE)) は、Python のAPIシグネチャを示す典型的な構造です。これらの有無もチェックします。

    • 本文テキストの長さ: クリーンアップされたプレーンテキストの長さが、指定された最小許容長さ min_text_len（デフォルト300文字）よりも短い場合、コンテンツが不十分であると判断します。

    • タイトルのみのページの補助判定: メインテキストに「プログラム仕様」や「API」といった一般的なタイトルを示すキーワードが含まれているにもかかわらず、APIマーカーが全くなく、かつテキスト長が比較的短い（デフォルト1000文字未満）場合、そのページがAPIの具体的な内容を欠いていると判断する補助的な基準として用います。

これらの基準のいずれか、または組み合わせに該当する場合、プログラムは当該HTMLファイルがAPI取り込みに失敗した疑いがあるものと判断し、その理由を記録します。

必要な非標準ライブラリとインストール方法

check_sphinx_api_html.py は、Python の標準ライブラリ（argparse, re, sys, pathlib, html）のみを使用しており、特別な非標準ライブラリは必要ありません。そのため、追加のインストール手順は不要です。

Python がインストールされていれば、そのまま実行できます。

必要な入力ファイル

このプログラムが動作するために必要な入力ファイルは、Sphinx によって生成されたHTMLファイル群です。

  • ファイルの種類: HTMLファイル

  • ファイル名パターン: デフォルトでは *_api.html というワイルドカードパターンに一致するファイル。このパターンは --files オプションで変更可能です。

  • 配置場所: デフォルトでは ./build/html ディレクトリ以下に存在することを期待します。このルートディレクトリは --root オプションで変更可能です。

  • 内容: これらのHTMLファイルは、通常、Sphinx の autodoc ディレクティブ（例: .. automodule::, .. autoclass::, .. autofunction:: など）を含む reStructuredText や Markdown ソースファイルから生成されていることが前提となります。

例: 以下のようなファイル構造を想定しています。

.
└── build/
    └── html/
        ├── index.html
        ├── modules.html
        ├── my_project.html
        ├── my_project.api.html  <-- 対象ファイル
        ├── my_project.sub_module.api.html  <-- 対象ファイル
        └── _static/

生成される出力ファイル

check_sphinx_api_html.py が生成する出力ファイルは1種類です。

  • ファイル名:

    • デフォルト: failed_api_html.txt

    • --outfile オプションで指定可能。

  • 内容:

    • API取り込みに失敗したと判断されたHTMLファイルの相対パスが、1行に1ファイルずつ記述されます。

    • パスは、--root オプションで指定されたルートディレクトリからの相対パスとなります。

    • パス区切り文字は、Windows環境であっても / に統一されます。

出力ファイルの例 (failed_api_html.txt):

my_project.api.html
my_project.sub_module.api.html
another_module.func.api.html

コマンドラインでの使用例 (Usage)

check_sphinx_api_html.py は、以下のコマンドライン引数をサポートしています。

python check_sphinx_api_html.py [-h] [--root ROOT] [--files FILES] [--outfile OUTFILE] [--exclude EXCLUDE] [--min-text-len MIN_TEXT_LEN] [--show-ok {0,1}]

  • -h, --help: ヘルプメッセージを表示して終了します。

  • --root ROOT: 検索を開始するルートディレクトリを指定します。

    • デフォルト: ./build/html

  • --files FILES: 対象とするHTMLファイルのワイルドカードパターンを指定します。

    • デフォルト: *_api.html

  • --outfile OUTFILE: 失敗したファイルのパスを書き込む出力ファイルのパスを指定します。

    • デフォルト: failed_api_html.txt

  • --exclude EXCLUDE: 検索パスから除外するキーワードを指定します。このオプションは複数回使用できます。指定されたキーワードがファイルパスの一部に含まれる場合、そのファイルはスキップされます。

    • 例: --exclude _templates --exclude deprecated

  • --min-text-len MIN_TEXT_LEN: 本文テキストの最小許容長さを指定します。これより短い場合は失敗と見なされる可能性があります。

    • デフォルト: 300

  • --show-ok {0,1}: 正常（OK）と判断されたファイルもコンソールに表示するかどうかを指定します。1 で表示、0 で非表示。

    • デフォルト: 0

コマンドラインでの具体的な使用例

1. 基本的な実行

デフォルトの検索ルート (./build/html) とファイルパターン (*_api.html) を使用して、API取り込みに失敗したファイルを検出します。

python check_sphinx_api_html.py

実行結果の例:

root    : /path/to/your_project/build/html
pattern : *_api.html
found   : 15 files

[FAILED] my_project.api.html
         - no autodoc API markers
         - main text too short: 85 < 300
         - looks like title-only API page
[OK]     my_project.sub_module.func_a.api.html
[FAILED] my_project.sub_module.class_b.api.html
         - no autodoc API markers
         - main text too short: 120 < 300

failed  : 2 / 15
output  : /path/to/your_project/failed_api_html.txt

この例では、my_project.api.html と my_project.sub_module.class_b.api.html の2つのファイルがAPI取り込みに失敗したと判断されました。failed_api_html.txt にはこれらのファイルの相対パスが記述されます。

failed_api_html.txt の内容:

my_project.api.html
my_project.sub_module.class_b.api.html

2. 特定のルートディレクトリを指定して実行

_build/html 以外のディレクトリにHTMLファイルがある場合に、そのディレクトリを検索ルートとして指定します。

python check_sphinx_api_html.py --root ../docs/_build/html

3. 特定のファイルパターンを指定して実行

*_api.html 以外の命名規則のファイルもチェックしたい場合や、より一般的なHTMLファイルを対象にしたい場合にパターンを指定します。

python check_sphinx_api_html.py --files "*.html" --root _build/html --outfile all_failed_html.txt

このコマンドは、_build/html 以下のすべてのHTMLファイル (*.html) を対象とし、結果を all_failed_html.txt に出力します。

4. 特定のパスを除外して実行

特定のサブディレクトリやファイル名の一部をチェック対象から除外したい場合に使用します。例えば、_templates ディレクトリ内のHTMLファイルや、deprecated というキーワードを含むパスを除外します。

python check_sphinx_api_html.py --exclude _templates --exclude deprecated

5. 最小テキスト長を変更して実行

より厳密に、またはより緩やかに本文の短さを判定したい場合に min-text-len を調整します。

python check_sphinx_api_html.py --min-text-len 500

6. 正常なファイルも表示して実行

チェックが正常に完了したファイルもコンソールに表示したい場合に使用します。

python check_sphinx_api_html.py --show-ok 1

実行結果の例:

root    : /path/to/your_project/build/html
pattern : *_api.html
found   : 15 files

[FAILED] my_project.api.html
         - no autodoc API markers
         - main text too short: 85 < 300
         - looks like title-only API page
[OK]     my_project.sub_module.func_a.api.html
[OK]     my_project.sub_module.func_b.api.html
[FAILED] my_project.sub_module.class_b.api.html
         - no autodoc API markers
         - main text too short: 120 < 300
[OK]     my_project.other_module.api.html

failed  : 2 / 15
output  : /path/to/your_project/failed_api_html.txt