Documentation Coverage

Documentation coverage counts how many publicly accessible members (packages, modules, classes, methods, functions, variables, …) are documented using a Python doc-string. Based on the count of possibly documented public members and the actual number of non-empty doc-strings, a percentage of documentation coverage can be computed.

Documentation coverage is a measure of code quality, which expresses how well documented (completeness or documentation, but not necessarily quality/helpfulness of documentation) source code is. Well documented code helps to use and maintain the existing code base. It also allows for automated documentation generation.

Depending on quality standards, a coverage goal (or limit) like 90% might be defined, which considers an overall documentation coverage less then 90% as FAILED. Such a limit might be enforced by maintainers or merge rules (via CI jobs). This ensures new code introduced by merge requests (pull requests) cannot decrease the once achieved overall project’s code quality.

Quick Configuration

See the overview page on how to setup and enable the Sphinx extension in general.

Note

This is a quick and minimal configuration. See below detailed explanations.

  1. Configure one or more Python packages for documentation coverage analysis in conf.py by adding a new ‘section’ defining some configuration variables. Each package is identified by an ID, which is later referred to by the report directive. Here, the ID is called src (dictionary key). Each package needs 4 configuration entries:

    name

    Name of the Python package [1].

    directory

    The directory of the package to analyze.

    fail_below

    An integer value in range 0..100, for when a documentation coverage is considered FAILED.

    levels

    A dictionary of coverage limits, their description and CSS style classes.

    # ==============================================================================
# Sphinx-reports - DocCov
# ==============================================================================
report_doccov_packages = {
   "src": {
      "name":       "myPackage",
      "directory":  "../myPackage",
      "fail_below": 80,
      "levels": {
         30:      {"class": "report-cov-below30",  "desc": "almost undocumented"},
         50:      {"class": "report-cov-below50",  "desc": "poorly documented"},
         80:      {"class": "report-cov-below80",  "desc": "roughly documented"},
         90:      {"class": "report-cov-below90",  "desc": "well documented"},
         100:     {"class": "report-cov-below100", "desc": "excellent documented"},
         "error": {"class": "report-cov-error",    "desc": "internal error"},
      },
   }
}

  2. Add the report:doc-coverage directive into your Restructured Text (ReST) document.

    .. report:doc-coverage::
   :packageid: src

Example Document

The following DocCoverage document is an example on how this documentation uses the report:doc-coverage directive. The first file consists of three parts: At first, a headline; at second second a short introduction paragraph and at third, the report generating directive. The second file shows how to integrate that document into the navigation bar.

DocCoverage.rst

Documentation Coverage Report
#############################

Documentation coverage generated by `docstr-coverage <https://github.com/HunterMcGushion/docstr_coverage>`__.

.. report:doc-coverage::
   :packageid: src

index.rst

.. toctree::
   :caption: References and Reports
   :hidden:

   sphinx_reports/sphinx_reports
   unittests/index
   coverage/index
   Doc. Coverage Report <DocCoverage>
   Static Type Check Report ➚ <typing/index>

.. toctree::
   :caption: Appendix
   :hidden:

Directives

.. report:doc-coverage::

Add a table summarizing the documentation coverage per Python source code file (packages and/or modules).

:packageid:

An identifier referencing a dictionary entry in the configuration variable report_doccov_packages defined in conf.py.

:legend:

Describes if and where to add a legend. Possible values: no_legend, top, bottom, both.

.. report:doc-coverage-legend::
:style:

Specifies the legend style. Default is horizontal-table.

Possible values:

  • default

  • horizontal-table

  • vertical-table

Roles

There are no roles defined.

Footnotes