check_sphinx_api_html プログラム仕様
Sphinxで生成された *_api.html を走査し、autodoc/API取り込みに失敗して本文が空っぽに近いHTMLを検出するスクリプト。
- 概要:
Sphinxで生成されたAPIドキュメントHTMLファイル（通常 *_api.html）を分析し、 Sphinxのautodoc機能がAPI要素を適切に抽出し、本文コンテンツを生成できなかったページを特定します。 これにより、ドキュメント生成プロセスの問題を早期に発見するのに役立ちます。
- 詳細説明:
スクリプトは指定されたディレクトリ以下のHTMLファイルを走査し、各ファイルのメインコンテンツ領域を抽出します。 抽出されたコンテンツからHTMLタグを除去してプレーンテキストを生成し、 そのテキストの長さや、典型的なSphinx autodocマーカーの存在をチェックします。 本文が極端に短い、またはAPIマーカーが見つからない場合、そのページはAPI取り込みに失敗したと判断され、 そのファイルパスと失敗理由が出力されます。
- 例:
python check_sphinx_api_html.py python check_sphinx_api_html.py --root _build/html python check_sphinx_api_html.py --root _build/html --files "*_api.html" python check_sphinx_api_html.py --outfile failed_api_files.txt
- 関連リンク:
- sphinx_.check_sphinx_api_html.check_api_html(path: Path, min_text_len: int = 300) tuple[bool, list[str]][ソース]
指定されたHTMLファイルがSphinx autodocによるAPIドキュメントとして適切に生成されているかをチェックする。
ファイルを読み込み、メインのHTMLコンテンツを抽出し、そこからテキストを整形します。 Sphinx autodocの典型的なマーカーが存在するか、本文のテキスト長が短いか、 あるいはタイトルのみのページのように見えるかなどを基準に、API取り込みの失敗を判定します。
- パラメータ:
path -- Path チェック対象のHTMLファイルのパス。
min_text_len -- int 本文テキストの最小許容長さ。これより短い場合は失敗と見なされる可能性がある。
- 戻り値:
tuple[bool, list[str]] failed (bool): 失敗の疑いがある場合は True、そうでない場合は False。 reasons (list[str]): 失敗と判断された理由のリスト。
- sphinx_.check_sphinx_api_html.extract_main_html(html: str) str[ソース]
Sphinx ReadTheDocs系HTMLから本文領域っぽい部分を抜く。
複数の正規表現パターンを順に試し、role="main" や class="document" などの要素を含む HTMLの主要コンテンツ領域を抽出します。 いずれのパターンにもマッチしない場合は、元のHTML全体を返します。
- パラメータ:
html -- str 処理対象のHTML文字列。
- 戻り値:
str 抽出された本文領域のHTML、または元のHTML全体。
- sphinx_.check_sphinx_api_html.find_files(root: Path, pattern: str) list[Path][ソース]
指定されたルートディレクトリ以下からワイルドカードパターンに一致するファイルを再帰的に検索する。
Path.rglob() を使用して、ルートディレクトリ以下のすべてのファイルを再帰的に探索し、 指定されたワイルドカードパターン（例: *_api.html）に一致し、かつファイルであるパスを収集します。 結果はパスのリストとしてソートされて返されます。
- パラメータ:
root -- Path 検索を開始するルートディレクトリのパス。
pattern -- str 検索するファイルのワイルドカードパターン。
- 戻り値:
list[Path] パターンに一致したファイルのパスのリスト。
- sphinx_.check_sphinx_api_html.main() int[ソース]
スクリプトのメインエントリポイント。SphinxのAPIドキュメントの健全性チェックを実行する。
コマンドライン引数を解析し、指定されたルートディレクトリ内のファイルに対してAPIドキュメントのチェックを行います。 失敗したファイルをリストアップし、指定された出力ファイルにそれらのパスを書き込みます。
- 戻り値:
int 正常終了した場合は0、エラーが発生した場合は1。