v0.3.0

.github/workflows/Pipeline.yml

@@ -9,7 +9,7 @@ jobs:
     uses: pyTooling/Actions/.github/workflows/Parameters.yml@cov
     with:
       name: sphinx-eports
-#      python_version_list: "3.8 3.9 3.10 3.11 3.12 pypy-3.8 pypy-3.9 pypy-3.10"
+      python_version_list: "3.9 3.10 3.11 3.12 pypy-3.9 pypy-3.10"
 #      disable_list: "windows:pypy-3.8 windows:pypy-3.9 windows:pypy-3.10"
 
   UnitTesting:

README.md

@@ -47,7 +47,9 @@ Each report directive might require an individual configuration, therefore see t
 
 ## Documentation Coverage
 
-    DocCov: write introduction
+```
+DocCov: write introduction
+```
 
 
 ### Quick Configuration
@@ -61,7 +63,7 @@ details.
    directive. Here, the ID is called `src` (dictionary key). Each package needs 4 configuration entries:
 
    * `name`  
-     Name of the Python package[^PkgNameVsPkgDir].
+     Name of the Python package[^1].
    * `directory`  
      The directory of the package to analyze.
    * `fail_below`  
@@ -100,20 +102,29 @@ details.
       :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
 
-    CodeCov: write introduction
+```
+CodeCov: write introduction
+```
 
 
 ## Unit Test Summary
 
-    UnitTest: write introduction
+```
+UnitTest: write introduction
+```
 
 
 ## Dependencies
 
-    Dep: write introduction
+```
+Dep: write introduction
+```
 
 
 ## Contributors

doc/Examples/FullyDocumented.rst

@@ -0,0 +1,7 @@
+Fully Undocumented
+##################
+
+The following report shows a fully documented package.
+
+.. report:doc-coverage::
+   :packageid: documented

doc/Examples/PartiallyDocumented.rst

@@ -0,0 +1,7 @@
+Partially Documented
+####################
+
+The following report shows a partially documented package.
+
+.. report:doc-coverage::
+   :packageid: partially

doc/Examples/Undocumented.rst

@@ -0,0 +1,7 @@
+Undocumented
+############
+
+The following report shows an undocumented package.
+
+.. report:doc-coverage::
+   :packageid: undocumented

doc/Glossary.rst

@@ -9,10 +9,22 @@ Glossary
    Code Coverage
      tbd
 
-   Documentation Coverage
+   doc-string
      tbd
 
-   Python doc-string
+     .. code-block:: Python
+
+        def myFunction(a: int, b: int) -> str:
+          """
+          Converts 2 integers to a tuple represented as a string.
+
+          :param a: First tuple element.
+          :param b: Second tuple element.
+          :returns: The tuple ``"(a, b)"`` as a string.
+          """
+          return f"({a}, {b})"
+
+   Documentation Coverage
      tbd
 
    Statement Coverage

doc/_static/css/override.css

@@ -99,27 +99,3 @@ section > p,
 	padding-left: 0;
 	padding-right: 0;
 }
-
-.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td {
-	background-color: unset;
-}
-
-.doccov-below100 {
-	background: rgba(0, 200, 82, .4);
-}
-.doccov-below90 {
-	background: rgba(0, 200, 82, .2);
-}
-.doccov-below80 {
-	background: rgba(255, 145, 0, .2);
-}
-.doccov-below50 {
-	background: rgba(255, 82, 82, .2);
-}
-.doccov-below30 {
-	background: rgba(101, 31, 255, .2);
-}
-
-.doccov-summary-row {
-	font-weight: bold;
-}

doc/conf.py

@@ -261,18 +261,38 @@
 # ==============================================================================
 # Sphinx-reports - DocCov
 # ==============================================================================
+_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"}
+}
+
 report_doccov_packages = {
 	"src": {
 		"name":       "sphinx_reports",
 		"directory":  "../sphinx_reports",
 		"fail_below": 80,
-		"levels": {
-			30:  {"class": "doccov-below30",  "background": "rgba(101,  31, 255, .2)", "desc": "almost undocumented"},
-			50:  {"class": "doccov-below50",  "background": "rgba(255,  82,  82, .2)", "desc": "poorly documented"},
-			80:  {"class": "doccov-below80",  "background": "rgba(255, 145,   0, .2)", "desc": "roughly documented"},
-			90:  {"class": "doccov-below90",  "background": "rgba(  0, 200,  82, .2)", "desc": "well documented"},
-			100: {"class": "doccov-below100", "background": "rgba(  0, 200,  82, .2)", "desc": "excellent documented"}
-		}
+		"levels":     _levels
+	},
+	"undocumented": {
+		"name":       "undocumented",
+		"directory":  "../tests/packages/undocumented",
+		"fail_below": 80,
+		"levels":     _levels
+	},
+	"partially": {
+		"name":       "partially",
+		"directory":  "../tests/packages/partially",
+		"fail_below": 80,
+		"levels":     _levels
+	},
+	"documented": {
+		"name":       "documented",
+		"directory":  "../tests/packages/documented",
+		"fail_below": 80,
+		"levels":     _levels
 	}
 }
 

doc/index.rst

@@ -152,7 +152,9 @@ License
    :caption: Examples
    :hidden:
 
-
+   Examples/Undocumented
+   Examples/PartiallyDocumented
+   Examples/FullyDocumented
 
 .. toctree::
    :caption: Supported Reports

run.ps1

@@ -97,7 +97,7 @@ if ($install)
   { Write-Host -ForegroundColor Cyan     "[ADMIN][UNINSTALL] Uninstalling $PackageName ..."
     py -3.12 -m pip uninstall -y $PackageName
     Write-Host -ForegroundColor Cyan     "[ADMIN][INSTALL]   Installing $PackageName from wheel ..."
-    py -3.12 -m pip install .\dist\$PackageName-0.2.0-py3-none-any.whl
+    py -3.12 -m pip install .\dist\$PackageName-0.3.0-py3-none-any.whl
 
     Write-Host -ForegroundColor Cyan     "[ADMIN][INSTALL]   Closing window in 5 seconds ..."
     Start-Sleep -Seconds 5

setup.py

@@ -30,7 +30,7 @@
 #
 """Package installer for 'Write version information for any programming language as source file'."""
 from pathlib             import Path
-from pyTooling.Packaging import DescribePythonPackageHostedOnGitHub
+from pyTooling.Packaging import DescribePythonPackageHostedOnGitHub, DEFAULT_CLASSIFIERS
 
 gitHubNamespace =        "pyTooling"
 packageName =            "sphinx_reports"
@@ -42,4 +42,16 @@
 	description="A Sphinx extension providing coverage details embedded in documentation pages.",
 	gitHubNamespace=gitHubNamespace,
 	sourceFileWithVersion=packageInformationFile,
+	classifiers=DEFAULT_CLASSIFIERS + [
+		"Framework :: Sphinx",
+		"Framework :: Sphinx :: Domain",
+		"Framework :: Sphinx :: Extension",
+		"Topic :: Documentation :: Sphinx",
+		"Topic :: Software Development :: Documentation",
+		"Topic :: Software Development :: Quality Assurance",
+	],
+	developmentStatus="beta",
+	dataFiles={
+		"sphinx_reports": ["static/*.css"]
+	}
 )

sphinx_reports/Adapter/DocStrCoverage.py

@@ -32,28 +32,19 @@
 **A Sphinx extension providing coverage details embedded in documentation pages.**
 """
 from pathlib import Path
-from sys     import version_info
 from typing  import List
 
 from docstr_coverage                   import analyze, ResultCollection
 from docstr_coverage.result_collection import FileCount
 from pyTooling.Decorators              import export, readonly
 
 from sphinx_reports.Common                          import ReportExtensionError
-from sphinx_reports.DataModel.DocumentationCoverage import ModuleCoverage, PackageCoverage
+from sphinx_reports.DataModel.DocumentationCoverage import ModuleCoverage, PackageCoverage, AggregatedCoverage
 
 
 @export
 class DocStrCoverageError(ReportExtensionError):
-	# WORKAROUND: for Python <3.11
-	# Implementing a dummy method for Python versions before
-	__notes__: List[str]
-	if version_info < (3, 11):  # pragma: no cover
-		def add_note(self, message: str):
-			try:
-				self.__notes__.append(message)
-			except AttributeError:
-				self.__notes__ = [message]
+	pass
 
 
 @export
@@ -63,7 +54,7 @@ class Analyzer:
 	_moduleFiles:     List[Path]
 	_coverageReport:  str
 
-	def __init__(self, directory: Path, packageName: str):
+	def __init__(self, directory: Path, packageName: str) -> None:
 		self._searchDirectory = directory
 		self._packageName = packageName
 		self._moduleFiles = []
@@ -91,7 +82,7 @@ def CoverageReport(self) -> ResultCollection:
 		return self._coverageReport
 
 	def Analyze(self) -> ResultCollection:
-		self._coverageReport: ResultCollection = analyze(self._moduleFiles)
+		self._coverageReport: ResultCollection = analyze(self._moduleFiles, show_progress=False)
 		return self._coverageReport
 
 	def Convert(self) -> PackageCoverage:
@@ -102,10 +93,10 @@ def Convert(self) -> PackageCoverage:
 			perFileResult: FileCount = value.count_aggregate()
 
 			moduleName = path.stem
-			modulePath = [p.name for p in path.parents]
+			modulePath = [p.name for p in path.parents if p.name != ""]
 
-			currentCoverageObject = rootPackageCoverage
-			for packageName in modulePath[1:]:
+			currentCoverageObject: AggregatedCoverage = rootPackageCoverage
+			for packageName in modulePath:
 				try:
 					currentCoverageObject = currentCoverageObject[packageName]
 				except KeyError:
@@ -117,6 +108,11 @@ def Convert(self) -> PackageCoverage:
 			currentCoverageObject._expected = perFileResult.needed
 			currentCoverageObject._covered = perFileResult.found
 			currentCoverageObject._uncovered = perFileResult.missing
-			currentCoverageObject._coverage = perFileResult.coverage()
+
+			currentCoverageObject._uncovered = currentCoverageObject._expected - currentCoverageObject._covered
+			if currentCoverageObject._expected != 0:
+				currentCoverageObject._coverage = currentCoverageObject._covered / currentCoverageObject._expected
+			else:
+				currentCoverageObject._coverage = 1.0
 
 		return rootPackageCoverage