debug_sphinx_build プログラム仕様

Sphinx autodocにおけるimportエラーを調査するためのユーティリティスクリプト。

各 .py ファイルを subprocess で個別 import することで、 Qt/Tk/matplotlib backend などの副作用が後続ファイルに残らないようにする。

debug_sphinx_build.py 技術ドキュメント

class sphinx_.debug_sphinx_build.DummyModule(name, doc=None)

ベースクラス: ModuleType

モックモジュールとして振る舞うダミークラス。

types.ModuleType を継承し、未定義の属性にアクセスされた際に DummyObject を動的に作成・設定する。

class sphinx_.debug_sphinx_build.DummyObject(name: str = 'dummy')

ベースクラス: object

モックオブジェクトとして振る舞うダミークラス。

属性アクセスや関数呼び出しがあってもエラーにならず、常に新しい DummyObject を返す。 これにより、実際のモジュールが存在しなくても参照エラーを防ぐ。

sphinx_.debug_sphinx_build.add_sys_paths(args, source_dir: Path) → None

コマンドライン引数に基づいて sys.path にパスを追加する。

args.add_cwd が真ならカレントディレクトリを、args.add_source が真なら ソースディレクトリを sys.path の先頭に追加する。 すでにパスが存在する場合は追加しない。

パラメータ:

  • args (argparse.Namespace) -- コマンドライン引数を格納する名前空間オブジェクト。

  • source_dir (Path) -- Sphinxのソースディレクトリのパス。

戻り値:

None

戻り値の型:

None

sphinx_.debug_sphinx_build.child_import_one_file(args) → None

子プロセスとして単一のPythonファイルをインポートする。

sys.path の設定、手動モック、conf.py 由来のモックを適用した後、 指定されたファイルをモジュールとしてロードする。 この関数は、--child-import 引数が指定された場合にメイン関数から呼び出される。

パラメータ:

args (argparse.Namespace) -- コマンドライン引数を格納する名前空間オブジェクト。

戻り値:

None

戻り値の型:

None

sphinx_.debug_sphinx_build.install_mock_modules(module_names: list[str]) → None

指定されたモジュール名を sys.modules にダミーモジュールとしてインストールする。

モジュール名が階層的（例: numpy.linalg）である場合、親モジュール (numpy) も ダミーモジュールとして追加される。

パラメータ:

module_names (list[str]) -- モックとしてインストールするモジュール名のリスト。

戻り値:

None

戻り値の型:

None

sphinx_.debug_sphinx_build.load_conf_mocks(source_dir: Path) → list[str]

conf.py から autodoc_mock_imports の設定を読み込む。

conf.py が存在しない場合は空のリストを返す。 autodoc_mock_imports がリストまたはタプルでない場合は警告を表示し、空リストを返す。

パラメータ:

source_dir (Path) -- Sphinxのソースディレクトリのパス。

戻り値:

autodoc_mock_imports に設定されたモックモジュール名のリスト。

戻り値の型:

list[str]

sphinx_.debug_sphinx_build.load_module_from_file(module_name: str, file_path: Path)

指定されたファイルパスからモジュールをロードし、sys.modules に追加する。

importlib.util を使用してモジュール仕様を作成し、ロードして実行する。

パラメータ:

  • module_name (str) -- ロードするモジュールの名前。

  • file_path (Path) -- ロードするモジュールのファイルパス。

戻り値:

ロードされたモジュールオブジェクト。

戻り値の型:

types.ModuleType

例外:

ImportError -- モジュール仕様の作成に失敗した場合。

sphinx_.debug_sphinx_build.main()

スクリプトのメインエントリポイント。

コマンドライン引数を解析し、親プロセスとして動作する場合は source ディレクトリ内の すべてのPythonファイルを子プロセスで順次インポートを試みる。 子プロセスとして動作する場合は、単一のファイルをインポートする (--child-import 指定時)。 エラーが発生した場合は記録し、最終的に概要を出力する。

sphinx_.debug_sphinx_build.make_module_name(source_dir: Path, py_file: Path) → str

ソースディレクトリとPythonファイルのパスから、一意なモジュール名を生成する。

ファイルパスをソースディレクトリからの相対パスに変換し、ファイル名をハイフンやスペースを アンダースコアに置換して、有効なPython識別子になるように調整する。 sphinx_debug. プレフィックスを付与する。

パラメータ:

  • source_dir (Path) -- Sphinxのソースディレクトリのパス。

  • py_file (Path) -- 対象のPythonファイルのパス。

戻り値:

生成されたモジュール名。

戻り値の型:

str

sphinx_.debug_sphinx_build.parse_mock_arg(mock_text: str) → list[str]

セミコロン区切りの文字列からモックモジュール名のリストを解析する。

空白文字列や空の要素は無視される。

パラメータ:

mock_text (str) -- セミコロン区切りのモックモジュール名文字列。

戻り値:

解析されたモックモジュール名のリスト。

戻り値の型:

list[str]

sphinx_.debug_sphinx_build.print_error_summary(errors: list[dict]) → None

記録されたエラーの概要をコンソールに出力する。

エラーがない場合はその旨を表示する。

パラメータ:

errors (list[dict]) -- 記録されたエラー情報のリスト。

戻り値:

None

戻り値の型:

None

sphinx_.debug_sphinx_build.raise_if_subprocess_failed(cp: CompletedProcess, py_file: Path) → None

サブプロセスが非ゼロの終了コードを返した場合に RuntimeError を発生させる。

パラメータ:

  • cp (subprocess.CompletedProcess) -- サブプロセスの実行結果を含む subprocess.CompletedProcess オブジェクト。

  • py_file (Path) -- サブプロセスで処理されたファイルのパス。

戻り値:

None

戻り値の型:

None

例外:

RuntimeError -- サブプロセスが失敗した場合。

sphinx_.debug_sphinx_build.record_error(errors: list[dict], phase: str, file_path: Path, exc: BaseException, stdout: str = '', stderr: str = '') → None

発生したエラー情報を記録リストに追加する。

エラーのフェーズ、ファイルパス、例外情報、標準出力、標準エラー出力などを 辞書形式で記録する。

パラメータ:

  • errors (list[dict]) -- エラー情報を格納するリスト。

  • phase (str) -- エラーが発生したフェーズ（例: "conf.py", "module"）。

  • file_path (Path) -- エラーが発生したファイルのパス。

  • exc (BaseException) -- 発生した例外オブジェクト。

  • stdout (str) -- サブプロセスの標準出力の内容。

  • stderr (str) -- サブプロセスの標準エラー出力の内容。

戻り値:

None

戻り値の型:

None

sphinx_.debug_sphinx_build.run_import_in_subprocess(args, source_dir: Path, py_file: Path) → CompletedProcess

指定されたPythonファイルを子プロセスでインポート実行する。

現在のスクリプト自体を python -m のように --child-import オプションを付けて実行し、 指定されたファイルのみをインポートさせる。 子プロセスの標準出力と標準エラー出力をキャプチャする。

パラメータ:

  • args (argparse.Namespace) -- コマンドライン引数を格納する名前空間オブジェクト。

  • source_dir (Path) -- Sphinxのソースディレクトリのパス。

  • py_file (Path) -- インポートするPythonファイルのパス。

戻り値:

サブプロセスの実行結果を含む subprocess.CompletedProcess オブジェクト。

戻り値の型:

subprocess.CompletedProcess

sphinx_.debug_sphinx_build.should_skip(py_file: Path) → tuple[bool, str]

特定の条件に基づいてPythonファイルを処理対象からスキップするかどうかを判定する。

conf.py、ファイル名が _docstring で終わるファイル、 ファイル名が _数字 で終わるファイルはスキップされる。

パラメータ:

py_file (Path) -- 検査対象のPythonファイルのパス。

戻り値:

スキップするかどうかを示す真偽値と、スキップ理由の文字列のタプル。

戻り値の型:

tuple[bool, str]