sphinx.ext.coverage – ドキュメント網羅率統計の収集¶
この拡張機能は、CoverageBuilderという追加のビルダーを備えています。
注意
sphinx-apidocコマンドは、プロジェクト内のすべてのコードのAPIドキュメントを自動的に生成するために使用でき、これらのドキュメントを手動で作成して最新の状態に保つ必要がなくなります。
警告
coverageは、ドキュメント化されるモジュールを**インポート**します。sphinx-buildが実行されると、インポート時に副作用のあるモジュールがある場合、それらの副作用が網羅率ビルダーによって実行されます。
ライブラリモジュールではなくスクリプトをドキュメント化する場合は、メインルーチンがif __name__ == '__main__'条件で保護されていることを確認してください。
注意
Sphinx（実際にはSphinxを実行するPythonインタープリター）がモジュールを見つけるには、インポート可能である必要があります。つまり、モジュールまたはパッケージはsys.pathのいずれかのディレクトリに存在する必要があります。設定ファイルでsys.pathをそれに応じて調整してください。
このビルダーを使用するには、設定ファイルでcoverage拡張機能を有効にして、コマンドラインでsphinx-build -M coverageを実行します。
ビルダー¶
設定¶
ビルダーが何をチェックするかを指定するために、いくつかの設定値を使用できます。
- coverage_modules¶
- 型：
list[str]- デフォルト：
[]
網羅率をテストするPythonパッケージまたはモジュールのリスト。これが指定されている場合、Sphinxは、このリストに提供されている各パッケージまたはモジュール、および各パッケージまたはモジュールで見つかったすべてのサブパッケージとサブモジュールをイントロスペクトします。これが指定されていない場合、Sphinxは認識しているPythonパッケージとモジュールの網羅率のみを提供します。つまり、
py:moduleディレクティブ（Pythonドメインで提供）またはautomoduleディレクティブ（autodoc拡張機能で提供）を使用してドキュメント化されているモジュールです。バージョン7.4で追加されました。
- coverage_ignore_modules¶
- coverage_ignore_functions¶
- coverage_ignore_classes¶
- coverage_ignore_pyobjects¶
Python正規表現のリスト。
これらの正規表現のいずれかがPythonオブジェクトの完全なインポートパスの任意の部分と一致する場合、そのPythonオブジェクトはドキュメント網羅率レポートから除外されます。
バージョン2.1で追加されました。
- coverage_c_path¶
- coverage_c_regexes¶
- coverage_ignore_c_items¶
- coverage_write_headline¶
見出しを書き込まないようにするには、
Falseに設定します。バージョン1.1で追加されました。
- coverage_skip_undoc_in_source¶
ソースでdocstringによってドキュメント化されていないオブジェクトをスキップします。デフォルトは
Falseです。バージョン1.1で追加されました。
- coverage_show_missing_items¶
欠落しているオブジェクトも標準出力に出力します。デフォルトは
Falseです。バージョン3.1で追加されました。
- coverage_statistics_to_report¶
網羅率統計の表形式レポートを網羅率レポートに出力します。デフォルトは
Trueです。出力例
+-----------------------+----------+--------------+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +-----------------------+----------+--------------+ | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+
バージョン7.2で追加されました。
- coverage_statistics_to_stdout¶
網羅率統計の表形式レポートを標準出力に出力します。デフォルトは
Falseです。出力例
+-----------------------+----------+--------------+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +-----------------------+----------+--------------+ | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+
バージョン7.2で追加されました。