check_sphinx_api_rst プログラム仕様

Sphinx の *_api.rst を再帰走査し、autodoc で問題になりやすい記述を検出するスクリプト。

詳細説明: このスクリプトは、Sphinxプロジェクト内の *_api.rst ファイルを走査し、 .. automodule:: ディレクティブに指定されたモジュール名に問題がないか、 また、対応するPythonファイルが argv や sys.argv を使用しているにもかかわらず if __name__ == "__main__": ガードがない可能性がないかをチェックします。

--fix オプションが指定された場合、モジュール名のハイフンやWindowsパス区切りを自動的に修正し、 関連するファイル名や参照も更新します。

チェック内容:

  1. .. automodule:: に指定されたモジュール名に '-' が含まれていないか。

  2. .. automodule:: に指定されたモジュール名に '' や '/' が含まれていないか。

  3. 対応する .py ファイルが argv / sys.argv を使っているのに if __name__ == "__main__": ガードが無い可能性がないか。

--fix の自動修正内容:

  • automodule の module-name 中の '' と '/' を '.' に置換。

  • automodule の module-name 中の '-' を '_' に置換。

  • 対応する .py ファイル名の '-' を '_' に置換。

  • 対応する *_api.rst ファイル名の '-' を '_' に置換。

  • 同じディレクトリ内の関連しそうな usage/examples/index rst/md 参照の '-' を '_' に置換。

例:

python check_sphinx_api_rst.py python check_sphinx_api_rst.py --root ./source python check_sphinx_api_rst.py --fix python check_sphinx_api_rst.py --fix --dry-run

check_sphinx_api_rst.py

sphinx_.check_sphinx_api_rst.check_one_rst(root: Path, rst_path: Path, fix: bool = False, dry_run: bool = False) → tuple[bool, list[str], list[str]][ソース]

1つの *_api.rst ファイルをチェックし、必要に応じて修正を試みる。

詳細説明: この関数は以下のチェックを行います。 - .. automodule:: ディレクティブが存在するか。 - モジュール名に不正な文字（'-', '', '/'）が含まれていないか。 - 対応するPythonファイルが見つかるか。 - 対応するPythonファイルに argv/sys.argv が __main__ ガードなしで使用されていないか。 fix がTrueの場合、不正なモジュール名を修正し、関連ファイルのリネームや内容置換を行います。 dry_run がTrueの場合、修正は実行されずにログに記録されるのみです。

パラメータ:

  • root -- Path: Sphinxソースのルートディレクトリ。

  • rst_path -- Path: チェック対象の *_api.rst ファイルのパス。

  • fix -- bool: Trueの場合、検出された問題を自動修正する。デフォルトはFalse。

  • dry_run -- bool: Trueの場合、修正をシミュレーションし、ファイルは変更しない。fix と併用。デフォルトはFalse。

戻り値:

tuple[bool, list[str], list[str]]: - bool: 問題が見つかった場合はTrue、それ以外はFalse。 - list[str]: 検出された問題の理由を説明する文字列のリスト。 - list[str]: fix モードで実行された（または実行予定の）修正内容を説明する文字列のリスト。

sphinx_.check_sphinx_api_rst.extract_automodule_names(rst_text: str) → list[str][ソース]

RST本文から .. automodule:: ディレクティブに指定されたモジュール名を抽出する。

パラメータ:

rst_text -- str: RSTファイルの全テキスト内容。

戻り値:

list[str]: 抽出されたモジュール名のリスト。

sphinx_.check_sphinx_api_rst.fallback_py_path_from_rst(rst_path: Path) → Path[ソース]

*_api.rst ファイルのパスから、同じディレクトリ内の対応するPythonファイル (.py) のパス候補を推定する。

詳細説明: ファイル名が *_api.rst の場合、_api 部分を除去して .py 拡張子を付けます。 例: regression/foo_api.rst は regression/foo.py に推定される。

パラメータ:

rst_path -- Path: *_api.rst ファイルのパス。

戻り値:

Path: 推定されたPythonファイルのパス候補。

sphinx_.check_sphinx_api_rst.find_files(root: Path, pattern: str) → list[Path][ソース]

指定されたルートディレクトリ以下から、ワイルドカードパターンに一致するファイルを再帰的に検索する。

パラメータ:

  • root -- Path: 検索を開始するルートディレクトリのパス。

  • pattern -- str: 検索するファイルのワイルドカードパターン（例: "*.rst"）。

戻り値:

list[Path]: 見つかったファイルのパスのリスト。パスはソートされている。

sphinx_.check_sphinx_api_rst.fix_module_name(root: Path, rst_path: Path, module_name: str, actions: list[str], dry_run: bool = False) → tuple[Path, str][ソース]

automodule ディレクティブのモジュール名をPythonの import 可能な形に補正し、関連ファイルを修正する。

詳細説明: - モジュール名内の '' と '/' を '.' に置換し、'-' を '_' に置換します。 - 対応するPythonファイル名（'-' を含む場合）をリネームします。 - RSTファイル内の automodule ディレクティブのモジュール名を修正します。 - RSTファイル名自体（'-' を含む場合）をリネームします。 - 同じディレクトリ内の関連ドキュメント（_usage, _examples, _index など）の参照も更新します。 dry_run がTrueの場合、実際のリネームやファイル書き換えは行いません。

パラメータ:

  • root -- Path: プロジェクトのルートディレクトリ。

  • rst_path -- Path: 現在処理中の *_api.rst ファイルのパス。

  • module_name -- str: automodule で指定された元のモジュール名。

  • actions -- list[str]: 実行された（または実行予定の）アクションを記録するリスト。

  • dry_run -- bool: Trueの場合、実際のリネームやファイル書き込みを行わない。デフォルトはFalse。

戻り値:

tuple[Path, str]: 修正後のRSTファイルのパスと修正後のモジュール名。

sphinx_.check_sphinx_api_rst.has_unprotected_argv(py_text: str) → bool[ソース]

Pythonコード内で argv または sys.argv が使用されており、かつ if __name__ == "__main__": ガードがないかを判定する。

詳細説明: この関数は厳密な制御フロー解析ではなく、Sphinx autodocで問題になりやすい典型的なパターンを検出するためのものです。 __main__ ガードが見つからない場合でも、argv の使用がない場合は False を返します。

パラメータ:

py_text -- str: Pythonファイルの全テキスト内容。

戻り値:

bool: argv が保護なしで使用されている場合はTrue、それ以外はFalse。

sphinx_.check_sphinx_api_rst.main() → int[ソース]

SphinxのAPIドキュメント (*_api.rst) のチェックと修正を行うメイン処理。

詳細説明: コマンドライン引数を解析し、指定されたルートディレクトリ以下の *_api.rst ファイルを検索します。 各ファイルに対して check_one_rst を呼び出し、問題の検出と必要に応じた修正を行います。 結果はコンソールに出力され、--outfile で指定されたファイルにも詳細が記録されます。 問題が見つかったファイルがある場合、終了コードは1となり、それ以外は0となります。

戻り値:

int: 終了コード。問題が見つかった場合は1、それ以外は0。

sphinx_.check_sphinx_api_rst.module_name_to_py_path(root: Path, module_name: str) → Path[ソース]

automodule ディレクティブのモジュール名から、対応するPythonファイル (.py) のパス候補を作成する。

例:

regression.adaptive_gaussian_ridge は root/regression/adaptive_gaussian_ridge.py に変換される。

パラメータ:

  • root -- Path: プロジェクトのルートディレクトリ。

  • module_name -- str: automodule で指定されたモジュール名。

戻り値:

Path: 対応するPythonファイルのパス候補。

sphinx_.check_sphinx_api_rst.read_text(path: Path) → str[ソース]

指定されたパスのテキストファイルを複数のエンコーディングで試行しながら読み込む。

詳細説明: UTF-8, CP932, Shift_JIS, Latin-1 の順でエンコーディングを試み、 いずれのエンコーディングでもデコードできなかった場合は、 バイト列として読み込み、UTF-8でエラーを置換しながらデコードします。

パラメータ:

path -- Path: 読み込むファイルのパス。

戻り値:

str: ファイルの内容を表す文字列。

sphinx_.check_sphinx_api_rst.rename_file(src: Path, dst: Path, actions: list[str], dry_run: bool = False) → Path[ソース]

ファイルをリネームする。宛先パスにファイルが既に存在する場合はリネームをスキップする。

詳細説明: src と dst が同じ場合は処理をスキップします。 src が存在しない場合も処理をスキップします。 dry_run がTrueの場合、実際のリネームは行わず、アクションログのみを記録します。

パラメータ:

  • src -- Path: 元ファイルのパス。

  • dst -- Path: 新しいファイルのパス。

  • actions -- list[str]: 実行された（または実行予定の）アクションを記録するリスト。

  • dry_run -- bool: Trueの場合、実際のリネームを行わない。デフォルトはFalse。

戻り値:

Path: 実際にリネームされた後のパス（またはリネームされなかった場合は元のパス）。

sphinx_.check_sphinx_api_rst.replace_automodule_name(rst_path: Path, old_module_name: str, new_module_name: str, actions: list[str], dry_run: bool = False) → None[ソース]

RSTファイル内の .. automodule:: ディレクティブに指定されたモジュール名のみを置換する。

詳細説明: 指定されたRSTファイルを開き、正規表現を用いて .. automodule:: の行を見つけ、 その中のモジュール名が old_module_name と一致した場合に new_module_name に置換します。 ファイル内容が変更された場合のみ、アクションログに記録し、ファイルに書き戻します。 dry_run がTrueの場合、実際のファイル書き込みは行いません。

パラメータ:

  • rst_path -- Path: 対象RSTファイルのパス。

  • old_module_name -- str: 置換対象の古いモジュール名。

  • new_module_name -- str: 置換後の新しいモジュール名。

  • actions -- list[str]: 実行された（または実行予定の）アクションを記録するリスト。

  • dry_run -- bool: Trueの場合、実際のファイル書き込みを行わない。デフォルトはFalse。

戻り値:

None

sphinx_.check_sphinx_api_rst.replace_in_file(path: Path, old: str, new: str, actions: list[str], dry_run: bool = False) → None[ソース]

指定されたファイル内の文字列を置換する。

詳細説明: ファイルが存在しない場合や、置換対象の文字列 old がファイル内に含まれていない場合は処理をスキップします。 dry_run がTrueの場合、実際のファイル書き込みは行わず、アクションログのみを記録します。

パラメータ:

  • path -- Path: 対象ファイルのパス。

  • old -- str: 置換対象の文字列。

  • new -- str: 置換後の文字列。

  • actions -- list[str]: 実行された（または実行予定の）アクションを記録するリスト。

  • dry_run -- bool: Trueの場合、実際のファイル書き込みを行わない。デフォルトはFalse。

戻り値:

None

sphinx_.check_sphinx_api_rst.safe_module_name(module_name: str) → str[ソース]

Pythonの import 文で安全に使用できるモジュール名に補正する。

詳細説明: - バックスラッシュ '' とスラッシュ '/' をピリオド '.' に置換します。 - ハイフン '-' をアンダースコア '_' に置換します。

パラメータ:

module_name -- str: 元のモジュール名。

戻り値:

str: 補正されたモジュール名。

sphinx_.check_sphinx_api_rst.write_text(path: Path, text: str, dry_run: bool = False) → None[ソース]

指定されたパスにUTF-8エンコーディングでテキストを書き込む。

詳細説明: dry_runがTrueの場合、ファイルの書き込みは行わず、処理をスキップします。

パラメータ:

  • path -- Path: 書き込むファイルのパス。

  • text -- str: 書き込むテキストの内容。

  • dry_run -- bool: Trueの場合、ファイルの書き込みを行わない。デフォルトはFalse。

戻り値:

None