.. _DOCCOV:

Documentation Coverage
######################

:term:`Documentation coverage` counts how many publicly accessible members (packages, modules, classes, methods,
functions, variables, ...) are documented using a Python :term:`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.


.. _DOCCOV/Quick:

Quick Configuration
*******************

See the :ref:`overview page <OVER>` 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 :file:`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 [#PkgNameVsPkgDir]_.

   ``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.

   .. code-block:: Python

      # ==============================================================================
      # 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 :rst:dir:`report:doc-coverage` directive into your Restructured Text (ReST) document.

   .. code-block:: ReST

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


.. _DOCCOV/Example:

Example Document
****************

The following ``DocCoverage`` document is an example on how this documentation uses the :rst:dir:`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.

.. admonition:: :file:`DocCoverage.rst`

   .. code-block:: ReST

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

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

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

.. admonition:: :file:`index.rst`

   .. code-block:: ReST

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

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

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


.. _DOCCOV/Directives:

Directives
**********

.. rst:directive:: report:doc-coverage

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

   .. rst:directive:option:: packageid

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

   .. rst:directive:option:: legend

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

.. rst:directive:: report:doc-coverage-legend

   .. rst:directive:option:: style

      Specifies the legend style. Default is ``horizontal-table``.

      Possible values:

      * ``default``
      * ``horizontal-table``
      * ``vertical-table``


.. _DOCCOV/Roles:

Roles
*****

*There are no roles defined.*

---------------------------------

.. rubric:: Footnotes

.. [#PkgNameVsPkgDir] Toplevel Python packages can reside in a directory not matching the package name. This is possible
   because the toplevel package name is set in the package installation description. This is not good practice, but
   possible and unfortunately widely used. E.g. ``src`` as directory name. See setuptools, etc. for more details.