#!/usr/bin/env python # -*- coding: utf-8 -*- """ 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 :doc:`check_sphinx_api_rst_usage` """ from __future__ import annotations import argparse import re import sys from pathlib import Path AUTOMODULE_RE = re.compile( r"(^\s*\.\.\s+automodule::\s+)([^\s]+)(\s*$)", flags=re.MULTILINE, ) MAIN_GUARD_RE = re.compile( r"if\s+__name__\s*==\s*['\"]__main__['\"]\s*:", flags=re.MULTILINE, ) ARGV_RE = re.compile( r"\b(?:sys\s*\.\s*)?argv\b" ) def read_text(path: Path) -> str: """ 指定されたパスのテキストファイルを複数のエンコーディングで試行しながら読み込む。 詳細説明: UTF-8, CP932, Shift_JIS, Latin-1 の順でエンコーディングを試み、 いずれのエンコーディングでもデコードできなかった場合は、 バイト列として読み込み、UTF-8でエラーを置換しながらデコードします。 :param path: Path: 読み込むファイルのパス。 :returns: str: ファイルの内容を表す文字列。 """ for enc in ("utf-8", "cp932", "shift_jis", "latin-1"): try: return path.read_text(encoding=enc) except UnicodeDecodeError: continue return path.read_bytes().decode("utf-8", errors="replace") def write_text(path: Path, text: str, dry_run: bool = False) -> None: """ 指定されたパスにUTF-8エンコーディングでテキストを書き込む。 詳細説明: dry_runがTrueの場合、ファイルの書き込みは行わず、処理をスキップします。 :param path: Path: 書き込むファイルのパス。 :param text: str: 書き込むテキストの内容。 :param dry_run: bool: Trueの場合、ファイルの書き込みを行わない。デフォルトはFalse。 :returns: None """ if dry_run: return path.write_text(text, encoding="utf-8") def find_files(root: Path, pattern: str) -> list[Path]: """ 指定されたルートディレクトリ以下から、ワイルドカードパターンに一致するファイルを再帰的に検索する。 :param root: Path: 検索を開始するルートディレクトリのパス。 :param pattern: str: 検索するファイルのワイルドカードパターン（例: "*.rst"）。 :returns: list[Path]: 見つかったファイルのパスのリスト。パスはソートされている。 """ return sorted(p for p in root.rglob(pattern) if p.is_file()) def extract_automodule_names(rst_text: str) -> list[str]: """ RST本文から `.. automodule::` ディレクティブに指定されたモジュール名を抽出する。 :param rst_text: str: RSTファイルの全テキスト内容。 :returns: list[str]: 抽出されたモジュール名のリスト。 """ return [m.group(2).strip() for m in AUTOMODULE_RE.finditer(rst_text)] def safe_module_name(module_name: str) -> str: """ Pythonの `import` 文で安全に使用できるモジュール名に補正する。 詳細説明: - バックスラッシュ '\\' とスラッシュ '/' をピリオド '.' に置換します。 - ハイフン '-' をアンダースコア '_' に置換します。 :param module_name: str: 元のモジュール名。 :returns: str: 補正されたモジュール名。 """ module_name = module_name.replace("\\", ".") module_name = module_name.replace("/", ".") module_name = module_name.replace("-", "_") return module_name def module_name_to_py_path(root: Path, module_name: str) -> Path: """ `automodule` ディレクティブのモジュール名から、対応するPythonファイル (.py) のパス候補を作成する。 例: `regression.adaptive_gaussian_ridge` は `root/regression/adaptive_gaussian_ridge.py` に変換される。 :param root: Path: プロジェクトのルートディレクトリ。 :param module_name: str: `automodule` で指定されたモジュール名。 :returns: Path: 対応するPythonファイルのパス候補。 """ parts = module_name.split(".") return root.joinpath(*parts).with_suffix(".py") def fallback_py_path_from_rst(rst_path: Path) -> Path: """ `*_api.rst` ファイルのパスから、同じディレクトリ内の対応するPythonファイル (.py) のパス候補を推定する。 詳細説明: ファイル名が `*_api.rst` の場合、`_api` 部分を除去して `.py` 拡張子を付けます。 例: `regression/foo_api.rst` は `regression/foo.py` に推定される。 :param rst_path: Path: `*_api.rst` ファイルのパス。 :returns: Path: 推定されたPythonファイルのパス候補。 """ stem = rst_path.stem if stem.endswith("_api"): stem = stem[:-4] return rst_path.with_name(stem + ".py") def has_unprotected_argv(py_text: str) -> bool: """ Pythonコード内で `argv` または `sys.argv` が使用されており、かつ `if __name__ == "__main__":` ガードがないかを判定する。 詳細説明: この関数は厳密な制御フロー解析ではなく、Sphinx autodocで問題になりやすい典型的なパターンを検出するためのものです。 `__main__` ガードが見つからない場合でも、`argv` の使用がない場合は `False` を返します。 :param py_text: str: Pythonファイルの全テキスト内容。 :returns: bool: `argv` が保護なしで使用されている場合はTrue、それ以外はFalse。 """ result = bool(MAIN_GUARD_RE.search(py_text)) if result: return False result = bool(ARGV_RE.search(py_text)) if result: # print("py_text:", py_text) # 既存のコメントアウトを保持 return True return False def rename_file(src: Path, dst: Path, actions: list[str], dry_run: bool = False) -> Path: """ ファイルをリネームする。宛先パスにファイルが既に存在する場合はリネームをスキップする。 詳細説明: `src` と `dst` が同じ場合は処理をスキップします。 `src` が存在しない場合も処理をスキップします。 `dry_run` がTrueの場合、実際のリネームは行わず、アクションログのみを記録します。 :param src: Path: 元ファイルのパス。 :param dst: Path: 新しいファイルのパス。 :param actions: list[str]: 実行された（または実行予定の）アクションを記録するリスト。 :param dry_run: bool: Trueの場合、実際のリネームを行わない。デフォルトはFalse。 :returns: Path: 実際にリネームされた後のパス（またはリネームされなかった場合は元のパス）。 """ if src == dst: return src if not src.exists(): return src if dst.exists(): actions.append(f"SKIP rename because destination exists: {src} -> {dst}") return src actions.append(f"RENAME {src} -> {dst}") if not dry_run: src.rename(dst) return dst def replace_in_file(path: Path, old: str, new: str, actions: list[str], dry_run: bool = False) -> None: """ 指定されたファイル内の文字列を置換する。 詳細説明: ファイルが存在しない場合や、置換対象の文字列 `old` がファイル内に含まれていない場合は処理をスキップします。 `dry_run` がTrueの場合、実際のファイル書き込みは行わず、アクションログのみを記録します。 :param path: Path: 対象ファイルのパス。 :param old: str: 置換対象の文字列。 :param new: str: 置換後の文字列。 :param actions: list[str]: 実行された（または実行予定の）アクションを記録するリスト。 :param dry_run: bool: Trueの場合、実際のファイル書き込みを行わない。デフォルトはFalse。 :returns: None """ if not path.is_file(): return text = read_text(path) if old not in text: return new_text = text.replace(old, new) actions.append(f"REPLACE in {path}: {old} -> {new}") write_text(path, new_text, dry_run=dry_run) def 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の場合、実際のファイル書き込みは行いません。 :param rst_path: Path: 対象RSTファイルのパス。 :param old_module_name: str: 置換対象の古いモジュール名。 :param new_module_name: str: 置換後の新しいモジュール名。 :param actions: list[str]: 実行された（または実行予定の）アクションを記録するリスト。 :param dry_run: bool: Trueの場合、実際のファイル書き込みを行わない。デフォルトはFalse。 :returns: None """ if not rst_path.is_file(): return text = read_text(rst_path) def repl(m: re.Match) -> str: prefix, name, suffix = m.group(1), m.group(2), m.group(3) if name == old_module_name: return prefix + new_module_name + suffix return m.group(0) new_text = AUTOMODULE_RE.sub(repl, text) if new_text != text: actions.append(f"REPLACE automodule in {rst_path}: {old_module_name} -> {new_module_name}") write_text(rst_path, new_text, dry_run=dry_run) def 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の場合、実際のリネームやファイル書き換えは行いません。 :param root: Path: プロジェクトのルートディレクトリ。 :param rst_path: Path: 現在処理中の `*_api.rst` ファイルのパス。 :param module_name: str: `automodule` で指定された元のモジュール名。 :param actions: list[str]: 実行された（または実行予定の）アクションを記録するリスト。 :param dry_run: bool: Trueの場合、実際のリネームやファイル書き込みを行わない。デフォルトはFalse。 :returns: tuple[Path, str]: 修正後のRSTファイルのパスと修正後のモジュール名。 """ fixed_module_name = safe_module_name(module_name) if fixed_module_name == module_name: return rst_path, module_name old_py = module_name_to_py_path(root, module_name) new_py = module_name_to_py_path(root, fixed_module_name) # path separator が混じる場合、old_py は実在パスとして解決できないことがある。 # その場合は rst ファイル名から同名 .py を推定する。 if not old_py.is_file(): fallback_old_py = fallback_py_path_from_rst(rst_path) fallback_new_py = fallback_old_py.with_name(fallback_old_py.name.replace("-", "_")) if fallback_old_py.is_file(): old_py = fallback_old_py new_py = fallback_new_py # .py ファイル名の '-' は '_' へリネームする。 # '\' -> '.' の修正だけなら、通常 .py のリネームは不要。 if "-" in old_py.name: rename_file(old_py, new_py, actions, dry_run=dry_run) # rst 内の automodule 名を必ず修正する。 replace_automodule_name( rst_path, module_name, fixed_module_name, actions, dry_run=dry_run, ) # rst ファイル名の '-' は '_' へリネームする。 new_rst_path = rst_path.with_name(rst_path.name.replace("-", "_")) actual_rst_path = rst_path if "-" in rst_path.name: actual_rst_path = rename_file(rst_path, new_rst_path, actions, dry_run=dry_run) # 同じディレクトリ内の関連ドキュメント参照も軽く直す。 old_stem = rst_path.stem.replace("_api", "") new_stem = old_stem.replace("-", "_") if old_stem != new_stem: target_dir = actual_rst_path.parent if not dry_run else rst_path.parent for ext in ("*.rst", "*.md"): for p in target_dir.glob(ext): replace_in_file(p, old_stem, new_stem, actions, dry_run=dry_run) replace_in_file(p, old_stem + "_api", new_stem + "_api", actions, dry_run=dry_run) replace_in_file(p, old_stem + "_usage", new_stem + "_usage", actions, dry_run=dry_run) replace_in_file(p, old_stem + "_examples", new_stem + "_examples", actions, dry_run=dry_run) replace_in_file(p, old_stem + "_index", new_stem + "_index", actions, dry_run=dry_run) for suffix in ("_usage", "_examples", "_index", "_api"): old_file = target_dir / f"{old_stem}{suffix}.rst" new_file = target_dir / f"{new_stem}{suffix}.rst" rename_file(old_file, new_file, actions, dry_run=dry_run) old_file = target_dir / f"{old_stem}{suffix}.md" new_file = target_dir / f"{new_stem}{suffix}.md" rename_file(old_file, new_file, actions, dry_run=dry_run) return actual_rst_path, fixed_module_name def 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の場合、修正は実行されずにログに記録されるのみです。 :param root: Path: Sphinxソースのルートディレクトリ。 :param rst_path: Path: チェック対象の `*_api.rst` ファイルのパス。 :param fix: bool: Trueの場合、検出された問題を自動修正する。デフォルトはFalse。 :param dry_run: bool: Trueの場合、修正をシミュレーションし、ファイルは変更しない。`fix` と併用。デフォルトはFalse。 :returns: tuple[bool, list[str], list[str]]: - bool: 問題が見つかった場合はTrue、それ以外はFalse。 - list[str]: 検出された問題の理由を説明する文字列のリスト。 - list[str]: `fix` モードで実行された（または実行予定の）修正内容を説明する文字列のリスト。 """ rst_text = read_text(rst_path) module_names = extract_automodule_names(rst_text) reasons: list[str] = [] actions: list[str] = [] if not module_names: reasons.append("no automodule directive found") return True, reasons, actions current_rst_path = rst_path for module_name0 in module_names: module_name = module_name0 fixed_module_name = safe_module_name(module_name) if fixed_module_name != module_name: if "-" in module_name: reasons.append(f"invalid module name contains '-': {module_name}") if "\\" in module_name or "/" in module_name: reasons.append(f"invalid module name contains path separator: {module_name}") if fix: current_rst_path, module_name = fix_module_name( root, current_rst_path, module_name, actions, dry_run=dry_run, ) else: module_name = fixed_module_name py_path = module_name_to_py_path(root, module_name) if not py_path.is_file(): fallback = fallback_py_path_from_rst(current_rst_path) if fallback.is_file(): py_path = fallback reasons.append( f"module path not found, fallback py file used: {py_path.relative_to(root)}" ) else: reasons.append( f"corresponding py file not found for module: {module_name}" ) continue py_text = read_text(py_path) if has_unprotected_argv(py_text): reasons.append( f"argv is used but __main__ guard was not found: {py_path.relative_to(root)}" ) # fix後に、修正対象だったハイフン/セパレータ理由は再評価して消す。 if fix and actions: new_text = read_text(current_rst_path) if current_rst_path.exists() else rst_text remaining_modules = extract_automodule_names(new_text) remaining_bad = [ m for m in remaining_modules if "-" in m or "\\" in m or "/" in m ] reasons = [ r for r in reasons if not r.startswith("invalid module name contains '-'") and not r.startswith("invalid module name contains path separator") ] for m in remaining_bad: reasons.append(f"invalid module name still contains invalid character: {m}") failed = len(reasons) > 0 return failed, reasons, actions def main() -> int: """ SphinxのAPIドキュメント (`*_api.rst`) のチェックと修正を行うメイン処理。 詳細説明: コマンドライン引数を解析し、指定されたルートディレクトリ以下の `*_api.rst` ファイルを検索します。 各ファイルに対して `check_one_rst` を呼び出し、問題の検出と必要に応じた修正を行います。 結果はコンソールに出力され、`--outfile` で指定されたファイルにも詳細が記録されます。 問題が見つかったファイルがある場合、終了コードは1となり、それ以外は0となります。 :returns: int: 終了コード。問題が見つかった場合は1、それ以外は0。 """ parser = argparse.ArgumentParser( description=( "Check Sphinx *_api.rst files for invalid automodule names and " "argv usage without __main__ guard in corresponding .py files." ) ) parser.add_argument( "--root", type=str, default="./source", help='Sphinx source root directory. default: "./source"', ) parser.add_argument( "--files", type=str, default="*_api.rst", help='wildcard pattern for target RST files. default: "*_api.rst"', ) parser.add_argument( "--outfile", type=str, default="failed_api_rst.txt", help='output file path. default: "failed_api_rst.txt"', ) parser.add_argument( "--exclude", action="append", default=[], help="exclude path keyword. Can be used multiple times.", ) parser.add_argument( "--show-ok", type=int, default=0, choices=[0, 1], help="show OK files too. default: 0", ) parser.add_argument( "--fix", action="store_true", help="automatically fix '-' and path separators in automodule names when safe.", ) parser.add_argument( "--dry-run", action="store_true", help="show planned fixes without modifying files. Use with --fix.", ) args = parser.parse_args() root = Path(args.root).resolve() outfile = Path(args.outfile) if not root.exists(): print(f"ERROR: root directory not found: {root}") return 1 files = find_files(root, args.files) print(f"root : {root}") print(f"pattern : {args.files}") print(f"found : {len(files)} files") print(f"fix : {args.fix}") print(f"dry-run : {args.dry_run}") print() failed_files: list[tuple[Path, list[str]]] = [] action_log: list[str] = [] checked_count = 0 skipped_count = 0 for path in files: if not path.exists(): # 直前の --fix でリネーム済みの場合など continue rel_str = str(path.relative_to(root)).replace("\\", "/") if any(x in rel_str for x in args.exclude): skipped_count += 1 if args.show_ok: print(f"[SKIP] {rel_str}") continue checked_count += 1 failed, reasons, actions = check_one_rst( root, path, fix=args.fix, dry_run=args.dry_run, ) action_log.extend(actions) if actions: print(f"[FIX] {rel_str}") for a in actions: print(f" - {a}") if failed: failed_files.append((path, reasons)) print(f"[FAILED] {rel_str}") for r in reasons: print(f" - {r}") elif args.show_ok and not actions: print(f"[OK] {rel_str}") print() print(f"checked : {checked_count}") print(f"skipped : {skipped_count}") print(f"failed : {len(failed_files)} / {checked_count}") print(f"actions : {len(action_log)}") with outfile.open("w", encoding="utf-8") as f: for path, reasons in failed_files: try: rel = path.relative_to(root) except ValueError: rel = path f.write(str(rel).replace("\\", "/")) f.write("\n") for r in reasons: f.write(f" - {r}\n") if action_log: f.write("\n[ACTIONS]\n") for a in action_log: f.write(f"- {a}\n") print(f"output : {outfile.resolve()}") return 1 if failed_files else 0 if __name__ == "__main__": sys.exit(main())