diff --git a/.btd.yml b/.btd.yml deleted file mode 100644 index 296c029b..00000000 --- a/.btd.yml +++ /dev/null @@ -1,9 +0,0 @@ -input: doc -output: _build -requirements: requirements.txt -target: gh-pages -formats: [ html ] -images: - base: btdi/sphinx:pytooling - latex: btdi/latex -theme: https://codeload.GitHub.com/buildthedocs/sphinx.theme/tar.gz/v1 diff --git a/README.md b/README.md index f0096fbf..68a60cfe 100644 --- 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,20 +95,14 @@ 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 @@ -116,11 +110,50 @@ framework like [pytest](https://github.com/pytest-dev/pytest), which also offers 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 index 332de37b..930061eb 100644 --- a/doc/CodeCov/index.rst +++ b/doc/CodeCov/index.rst @@ -25,8 +25,8 @@ See the :ref:`overview page ` 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 ` 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"},