sphinx-reports 0.1.0

A Sphinx extension providing coverage details embedded in documentation pages.

Sphinx Reports

The Sphinx extension sphinx_reports offers a set of directives to integrate reports and summaries into the documentation generated by Sphinx.

Supported format reports are:

• ✅ Documentation coverage (by docstr_coverage (or interrogate?))
• 🚧 Code coverage (by Coverage.py)
• 🚧 Unit Test summaries (by pytest)
• 🚧 Dependencies (reading requirements.txt files)

Extension Configuration

This README demonstrates a quick and minimal configuration for the Sphinx extension and it's provided directives. See the sphinx-reports documentation for more details.

At first, add the extension name to the list of extensions in conf.py, so the extension is loaded by Sphinx.

# Sphinx extensions
extensions = [
  # ...
  "sphinx_reports",
]

Each report directive might require an individual configuration, therefore see the next sections for details.

Documentation Coverage

DocCov: write introduction

Quick Configuration

This is a quick and minimal configuration for the documentation coverage directives. See documentation coverage documentation for more details.

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[^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.

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

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

   • packageid
     The ID used in conf.py to describe a Python package.
   • legend (optional)
     Position of the legend (NoLegend, Top, Bottom, Both)

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

Code Coverage

CodeCov: write introduction

Unit Test Summary

UnitTest: write introduction

Dependencies

Dep: write introduction

Contributors

• Patrick Lehmann (Maintainer)

License

This Python package (source code) is licensed under Apache License 2.0.

The accompanying documentation is licensed under Creative Commons - Attribution-4.0 (CC-BY 4.0).

---

SPDX-License-Identifier: Apache-2.0