Updated README.

pyTooling · Jan 12, 2024 · bd7ed5b · bd7ed5b
1 parent fb1ae96
commit bd7ed5b
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 37 deletions.
diff --git a/.btd.yml b/.btd.yml
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ documentation generated by Sphinx.
 Supported format reports are:
 * ✅ Documentation coverage (by [docstr_coverage](https://github.com/HunterMcGushion/docstr_coverage) (or `interrogate`?))
 * 🚧 Code coverage (by [Coverage.py](https://github.com/nedbat/coveragepy))
-  * ✅ Summary page (displaying `status.json`)
+  * ✅ Summary page (displaying `coverage.json`)
   * 🚧 Highlighted source code
 * 🚧 Unit Test summaries (by [pytest](https://github.com/pytest-dev/pytest))
 * 🚧 Dependencies (reading `requirements.txt` files)
@@ -49,9 +49,13 @@ Each report directive might require an individual configuration, therefore see t
 
 ## Documentation Coverage
 
-```
-DocCov: write introduction
-```
+*Documentation Coverage* counts how many publicly accessible members 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.
 
 
 ### Quick Configuration
@@ -64,14 +68,10 @@ details.
    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.
+   * `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.
 
    ```Python
    # ==============================================================================
@@ -95,32 +95,65 @@ details.
    ```
 2. Add the `doc-coverage` directive into your Restructured Text (ReST) document.
 
-   * `packageid`  
-     The ID used in `conf.py` to describe a Python package.
-   * `legend` (optional)  
-     Position of the legend (`no_legend`, `top`, `bottom`, `both`)
+   * `packageid` - The ID used in `conf.py` to describe a Python package.
+   * `legend` (optional) - Position of the legend (`no_legend`, `top`, `bottom`, `both`)
 
    ```Python
    .. report:doc-coverage::
       :packageid: src
    ```
 
-[^1]: 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.
-
 ## Code Coverage
 
 *Code Coverage* checks if a source code was used during execution. Usually, testcases are run by a testcase execution
 framework like [pytest](https://github.com/pytest-dev/pytest), which also offers to instrument the code for code
 coverage collection using the `pytest-cov` plugin. For Python, coverage collection is usually based on
 [Coverage.py](https://github.com/nedbat/coveragepy>), which supports statement and branch coverage collection.
 
+### Quick Configuration
 
-```
-CodeCov: write introduction
-```
+This is a quick and minimal configuration for the *code coverage* directives.
+See [code coverage](https://pyTooling.github.io/sphinx-reports/CodeCov/index.html) documentation for more
+details.
+
+1. Configure one or more coverage analysis reports in `conf.py` by adding a new 'section' defining some configuration
+   variables. Each analysis report is identified by an ID, which is later referred to by the report directive. Here, the
+   ID is called ``src`` (dictionary key). Each analysis report needs 4 configuration entries:
 
+   * `name` - Name of the Python package[^1].
+   * `json_report` - The code coverage report as JSON file as generated by *Coverage.py*.
+   * `fail_below` - An integer value in range 0..100, for when a code coverage is considered FAILED.
+   * `levels` - A dictionary of coverage limits, their description and CSS style classes.
+
+   ```Python
+   # ==============================================================================
+   # Sphinx-reports - DocCov
+   # ==============================================================================
+   report_codecov_packages = {
+     "src": {
+       "name":        "myPackage",
+       "json_report": "../report/coverage/coverage.json",
+       "fail_below":  80,
+       "levels": {
+         30:      {"class": "report-cov-below30",  "desc": "almost unused"},
+         50:      {"class": "report-cov-below50",  "desc": "poorly used"},
+         80:      {"class": "report-cov-below80",  "desc": "medium used"},
+         90:      {"class": "report-cov-below90",  "desc": "well well"},
+         100:     {"class": "report-cov-below100", "desc": "excellent used"},
+         "error": {"class": "report-cov-error",    "desc": "internal error"},
+       },
+     }
+   }
+   ```
+2. Add the `code-coverage` directive into your Restructured Text (ReST) document.
+
+   * `packageid` - The ID used in `conf.py` to describe a Python package.
+   * `legend` (optional) - Position of the legend (`no_legend`, `top`, `bottom`, `both`)
+
+   ```Python
+   .. report:code-coverage::
+      :packageid: src
+   ```
 
 ## Unit Test Summary
 
@@ -139,15 +172,20 @@ Dep: write introduction
 ## Contributors
 
 * [Patrick Lehmann](https://github.com/Paebbels) (Maintainer)
+* [and more...](https://GitHub.com/pyTooling/sphinx-reports/graphs/contributors)
 
 
 ## License
 
-This Python package (source code) is licensed under [Apache License 2.0](LICENSE.md).
-
+This Python package (source code) is licensed under [Apache License 2.0](LICENSE.md).  
 The accompanying documentation is licensed under Creative Commons - Attribution-4.0 (CC-BY 4.0).
 
 
 -------------------------
 
 SPDX-License-Identifier: Apache-2.0
+
+
+[^1]: 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.
diff --git a/doc/CodeCov/index.rst b/doc/CodeCov/index.rst
@@ -25,8 +25,8 @@ See the :ref:`overview page <OVER>` on how to setup and enable the Sphinx extens
    ``name``
      Name of the Python package[#PkgNameVsPkgDir]_.
 
-   ``html_report``
-     The directory of the generated code coverage HTML report as generated by *Coverage.py*.
+   ``json_report``
+     The code coverage report as JSON file as generated by *Coverage.py*.
 
    ``fail_below``
      An integer value in range 0..100, for when a code coverage is considered FAILED.
@@ -42,7 +42,7 @@ See the :ref:`overview page <OVER>` on how to setup and enable the Sphinx extens
       report_codecov_packages = {
          "src": {
             "name":        "myPackage",
-            "html_report": "../report/coverage/html",
+            "json_report": "../report/coverage/coverage.json",
             "fail_below":  80,
             "levels": {
                30:      {"class": "report-cov-below30",  "desc": "almost unused"},