Sphinx

# `sphinx.ext.coverage` – Collect doc coverage stats

This extension features one additional builder, the `CoverageBuilder`.

Todo

Write this section.

Note

The sphinx-apidoc command can be used to automatically generate API documentation for all code in a project, avoiding the need to manually author these documents and keep them up-to-date.

Warning

`coverage` imports the modules to be documented. If any modules have side effects on import, these will be executed by the coverage builder when `sphinx-build` is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a `if __name__ == '__main__'` condition.

Note

For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on `sys.path` – adapt your `sys.path` in the configuration file accordingly.

To use this builder, activate the coverage extension in your configuration file and run `sphinx-build -M coverage` on the command line.

## Builder

class sphinx.ext.coverage.CoverageBuilder

## Configuration

Several configuration values can be used to specify what the builder should check:

coverage_modules
  Type:
    `Sequence[str]`
  Default:
    `()`

  List of Python packages or modules to test coverage for. When this is provided, Sphinx will introspect each package or module provided in this list as well as all sub-packages and sub-modules found in each. When this is not provided, Sphinx will only provide coverage for Python packages and modules that it is aware of: that is, any modules documented using the `py:module` directive provided in the Python domain or the `automodule` directive provided by the `autodoc` extension.

  Added in version 7.4.

coverage_ignore_modules
coverage_ignore_functions
coverage_ignore_classes
coverage_ignore_pyobjects
  Type:
    `Sequence[str]`
  Default:
    `()`

  List of Python regular expressions.

  If any of these regular expressions matches any part of the full import path of a Python object, that Python object is excluded from the documentation coverage report.

  Added in version 2.1.

coverage_c_path
  Type:
    `Sequence[str]`
  Default:
    `()`

coverage_c_regexes
  Type:
    `dict[str, str]`
  Default:
    `{}`

coverage_ignore_c_items
  Type:
    `dict[str, Sequence[str]]`
  Default:
    `{}`

coverage_write_headline
  Type:
    `bool`
  Default:
    `True`

  Set to `False` to not write headlines.

  Added in version 1.1.

coverage_skip_undoc_in_source
  Type:
    `bool`
  Default:
    `False`

  Skip objects that are not documented in the source with a docstring.

  Added in version 1.1.

coverage_show_missing_items
  Type:
    `bool`
  Default:
    `False`

  Print objects that are missing to standard output also.

  Added in version 3.1.

coverage_statistics_to_report
  Type:
    `bool`
  Default:
    `True`

  Print a tabular report of the coverage statistics to the coverage report.

  Example output:

      +-----------------------+----------+--------------+
      | Module                | Coverage | Undocumented |
      +=======================+==========+==============+
      | package.foo_module    | 100.00%  | 0            |
      +-----------------------+----------+--------------+
      | package.bar_module    | 83.33%   | 1            |
      +-----------------------+----------+--------------+

  Added in version 7.2.

coverage_statistics_to_stdout
  Type:
    `bool`
  Default:
    `False`

  Print a tabular report of the coverage statistics to standard output.

  Example output:

      +-----------------------+----------+--------------+
      | Module                | Coverage | Undocumented |
      +=======================+==========+==============+
      | package.foo_module    | 100.00%  | 0            |
      +-----------------------+----------+--------------+
      | package.bar_module    | 83.33%   | 1            |
      +-----------------------+----------+--------------+

  Added in version 7.2.