sphinx.ext.coverage – Coleta estatísticas de cobertura da documentação

Essa extensão tem funcionalidades para construtor adicional, CoverageBuilder.

Nota

O comando sphinx-apidoc pode ser usado para gerar automaticamente a documentação da API para todo o código de um projeto, evitando a necessidade de criar manualmente esses documentos e mantê-los atualizados.

Aviso

coverage importa módulos para documentar. Se algum módulo tiver efeitos na importação, serão executados pelo construtor coverage quando sphinx-build for executado.

Se os scripts do seu documento, (diferentemente de módulos de biblioteca), certificar-se que suas rotinas principais estejam protegidas por uma condição if __name__ == '__main__'.

Nota

Para o Sphinx (na verdade, o interpretador Python que executa o Sphinx) para localizar seu módulo, ele deve ser importável. Isso significa que o módulo ou o pacote deve estar em um dos diretórios em sys.path – adapte seu sys.path no arquivo de configuração de acordo.

Para usar esse construtor, ativar a extensão de cobertura no arquivo de configuração e executar sphinx-build -M coverage na linha de comando.

Construtor

class sphinx.ext.coverage.CoverageBuilder[código-fonte]

Configuração

Vários valores de configuração podem ser usados para especificar o que o construtor deve verificar:

coverage_modules
Type:
Sequence[str]
Default:
()

Lista de pacotes ou módulos Python para testar a cobertura. Quando isso for fornecido, o Sphinx examinará cada pacote ou módulo fornecido nesta lista, bem como todos os subpacotes e submódulos encontrados em cada um. Quando isso não for fornecido, o Sphinx fornecerá cobertura apenas para pacotes e módulos Python que ele conhece: ou seja, quaisquer módulos documentados usando a diretiva py:module fornecida no domínio Python ou a diretiva automodule fornecida pela extensão autodoc.

Adicionado na versão 7.4.

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

Lista de expressões regulares do Python.

Se alguma dessas expressões regulares corresponder a qualquer parte do caminho completo de importação de um objeto Python, esse objeto Python será excluído do relatório de cobertura de documentação.

Adicionado na versão 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

Defina como False para não escrever títulos.

Adicionado na versão 1.1.

coverage_skip_undoc_in_source
Type:
bool
Default:
False

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

Adicionado na versão 1.1.

coverage_show_missing_items
Type:
bool
Default:
False

Print objects that are missing to standard output also.

Adicionado na versão 3.1.

coverage_statistics_to_report
Type:
bool
Default:
True

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

Exemplo de saída:

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

Adicionado na versão 7.2.

coverage_statistics_to_stdout
Type:
bool
Default:
False

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

Exemplo de saída:

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

Adicionado na versão 7.2.