sphinx.ext.coverage – 收集文件覆蓋率統計¶
此擴充功能提供一個額外的 builder，即 CoverageBuilder。
注意
可以使用 sphinx-apidoc 命令自動為專案中的所有程式碼產生 API 文件，避免需要手動撰寫這些文件並保持它們的最新狀態。
警告
coverage **匯入** 要記錄的文件模組。如果任何模組在匯入時有副作用，這些副作用將在執行 sphinx-build 時由 coverage builder 執行。
如果您記錄的是腳本（而不是程式庫模組），請確保它們的主要常式受到 if __name__ == '__main__' 條件的保護。
注意
為了讓 Sphinx（實際上是執行 Sphinx 的 Python 直譯器）找到您的模組，它必須是可匯入的。這表示該模組或套件必須位於 sys.path 上的其中一個目錄中 – 相應地調整您在設定檔中的 sys.path。
要使用此 builder，請在您的設定檔中啟用 coverage 擴充功能，並在命令列上執行 sphinx-build -M coverage。
Builder¶
設定¶
可以使用幾個設定值來指定 builder 應檢查的內容
- coverage_modules¶
- 類型:
Sequence[str]- 預設:
()
要測試覆蓋率的 Python 套件或模組清單。當提供此選項時，Sphinx 將檢查此清單中提供的每個套件或模組，以及在每個套件或模組中找到的所有子套件和子模組。當未提供此選項時，Sphinx 將僅為它知道的 Python 套件和模組提供覆蓋率：也就是說，任何使用
py:module指令（在 Python 網域 中提供）或automodule指令（由autodoc擴充功能提供）記錄的任何模組。在 7.4 版本中新增。
- coverage_ignore_modules¶
- coverage_ignore_functions¶
- coverage_ignore_classes¶
- coverage_ignore_pyobjects¶
- 類型:
Sequence[str]- 預設:
()
Python 正規表示式 的清單。
如果這些正規表示式中的任何一個與 Python 物件完整匯入路徑的任何部分匹配，則該 Python 物件將從文件覆蓋率報告中排除。
在 2.1 版本中新增。
- coverage_c_path¶
- 類型:
Sequence[str]- 預設:
()
- coverage_c_regexes¶
- 類型:
dict[str, str]- 預設:
{}
- coverage_ignore_c_items¶
- 類型:
dict[str, Sequence[str]]- 預設:
{}
- coverage_write_headline¶
- 類型:
bool- 預設:
True
設定為
False以不寫入標題。在 1.1 版本中新增。
- coverage_skip_undoc_in_source¶
- 類型:
bool- 預設:
False
跳過原始碼中未透過 docstring 記錄的文件物件。
在 1.1 版本中新增。
- coverage_show_missing_items¶
- 類型:
bool- 預設:
False
同時將遺失的物件列印到標準輸出。
在 3.1 版本中新增。
- coverage_statistics_to_report¶
- 類型:
bool- 預設:
True
將覆蓋率統計的表格報告列印到覆蓋率報告中。
範例輸出
+-----------------------+----------+--------------+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +-----------------------+----------+--------------+ | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+
在 7.2 版本中新增。
- coverage_statistics_to_stdout¶
- 類型:
bool- 預設:
False
將覆蓋率統計的表格報告列印到標準輸出。
範例輸出
+-----------------------+----------+--------------+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +-----------------------+----------+--------------+ | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+
在 7.2 版本中新增。