sphinx.ext.coverage – Erfassen von Dokumentationsabdeckungsstatistiken

Diese Erweiterung bietet einen zusätzlichen Builder, den CoverageBuilder.

Hinweis

Der Befehl sphinx-apidoc kann verwendet werden, um automatisch eine API-Dokumentation für allen Code in einem Projekt zu generieren, was die Notwendigkeit vermeidet, diese Dokumente manuell zu erstellen und aktuell zu halten.

Warnung

coverage importiert die zu dokumentierenden Module. Wenn Module Nebeneffekte beim Import haben, werden diese vom Coverage-Builder ausgeführt, wenn sphinx-build ausgeführt wird.

Wenn Sie Skripte (im Gegensatz zu Bibliotheksmodulen) dokumentieren, stellen Sie sicher, dass ihre Hauptroutine durch eine if __name__ == '__main__'-Bedingung geschützt ist.

Hinweis

Damit Sphinx (bzw. der Python-Interpreter, der Sphinx ausführt) Ihr Modul finden kann, muss es importierbar sein. Das bedeutet, dass das Modul oder das Paket sich in einem der Verzeichnisse auf sys.path befinden muss – passen Sie Ihr sys.path entsprechend in der Konfigurationsdatei an.

Um diesen Builder zu verwenden, aktivieren Sie die Coverage-Erweiterung in Ihrer Konfigurationsdatei und führen Sie sphinx-build -M coverage in der Befehlszeile aus.

Builder

class sphinx.ext.coverage.CoverageBuilder[source]

Konfiguration

Mehrere Konfigurationswerte können verwendet werden, um anzugeben, was der Builder prüfen soll

coverage_modules
Typ:
Sequenz[str]
Standard:
()

Liste der Python-Pakete oder Module, für die die Abdeckung getestet werden soll. Wenn dies angegeben ist, wird Sphinx jedes in dieser Liste bereitgestellte Paket oder Modul sowie alle darin gefundenen Unterpakete und Untermodule introspektieren. Wenn dies nicht angegeben ist, liefert Sphinx nur Abdeckung für Python-Pakete und Module, die ihm bekannt sind: d.h. alle Module, die mit der Direktive py:module in der Python-Domäne oder mit der Direktive automodule, die von der Erweiterung autodoc bereitgestellt wird, dokumentiert wurden.

Hinzugefügt in Version 7.4.

coverage_ignore_modules
coverage_ignore_functions
coverage_ignore_classes
coverage_ignore_pyobjects
Typ:
Sequenz[str]
Standard:
()

Liste von regulären Ausdrücken in Python.

Wenn einer dieser regulären Ausdrücke auf einen Teil des vollständigen Importpfads eines Python-Objekts zutrifft, wird dieses Python-Objekt vom Dokumentationsabdeckungsbericht ausgeschlossen.

Hinzugefügt in Version 2.1.

coverage_c_path
Typ:
Sequenz[str]
Standard:
()
coverage_c_regexes
Typ:
dict[str, str]
Standard:
{}
coverage_ignore_c_items
Typ:
dict[str, Sequence[str]]
Standard:
{}
coverage_write_headline
Typ:
bool
Standard:
True

Auf False setzen, um keine Überschriften zu schreiben.

Hinzugefügt in Version 1.1.

coverage_skip_undoc_in_source
Typ:
bool
Standard:
False

Überspringen Sie Objekte, die im Quellcode nicht mit einem Docstring dokumentiert sind.

Hinzugefügt in Version 1.1.

coverage_show_missing_items
Typ:
bool
Standard:
False

Geben Sie fehlende Objekte auch auf der Standardausgabe aus.

Hinzugefügt in Version 3.1.

coverage_statistics_to_report
Typ:
bool
Standard:
True

Geben Sie einen tabellarischen Bericht der Abdeckungsstatistiken im Abdeckungsbericht aus.

Beispielausgabe

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

Hinzugefügt in Version 7.2.

coverage_statistics_to_stdout
Typ:
bool
Standard:
False

Geben Sie einen tabellarischen Bericht der Abdeckungsstatistiken auf der Standardausgabe aus.

Beispielausgabe

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

Hinzugefügt in Version 7.2.