Fixed style and documentation issues.

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/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

sphinx_reports/CodeCoverage.py

@@ -122,13 +122,13 @@ def _ConvertToColor(self, currentLevel, configKey):
 		for levelLimit, levelConfig in self._levels.items():
 			if (currentLevel * 100) < levelLimit:
 				return levelConfig[configKey]
-		else:
-			return self._levels[100][configKey]
+
+		return self._levels[100][configKey]
 
 	def _GenerateCoverageTable(self) -> nodes.table:
 		# Create a table and table header with 5 columns
 		table, tableGroup = self._PrepareTable(
-			id=self._packageID,
+			identifier=self._packageID,
 			columns={
 				"Filename": 500,
 				"Total": 100,
@@ -189,10 +189,10 @@ def renderlevel(tableBody: nodes.tbody, packageCoverage: PackageCoverage, level:
 
 		return table
 
-	def _CreateLegend(self, id: str, classes: Iterable[str]) -> List[nodes.Element]:
+	def _CreateLegend(self, identifier: str, classes: Iterable[str]) -> List[nodes.Element]:
 		rubric = nodes.rubric("", text="Legend")
 
-		table = nodes.table("", id=id, classes=classes)
+		table = nodes.table("", id=identifier, classes=classes)
 
 		tableGroup = nodes.tgroup(cols=2)
 		table += tableGroup
@@ -231,11 +231,11 @@ def run(self):
 		container = nodes.container()
 
 		if LegendPosition.Top in self._legend:
-			container += self._CreateLegend(id="legend1", classes=["doccov-legend"])
+			container += self._CreateLegend(identifier="legend1", classes=["doccov-legend"])
 
 		container += self._GenerateCoverageTable()
 
 		if LegendPosition.Bottom in self._legend:
-			container += self._CreateLegend(id="legend2", classes=["doccov-legend"])
+			container += self._CreateLegend(identifier="legend2", classes=["doccov-legend"])
 
 		return [container]

sphinx_reports/DocCoverage.py

@@ -124,13 +124,13 @@ def _ConvertToColor(self, currentLevel, configKey):
 		for levelLimit, levelConfig in self._levels.items():
 			if (currentLevel * 100) < levelLimit:
 				return levelConfig[configKey]
-		else:
-			return self._levels[100][configKey]
+
+		return self._levels[100][configKey]
 
 	def _GenerateCoverageTable(self) -> nodes.table:
 		# Create a table and table header with 5 columns
 		table, tableGroup = self._PrepareTable(
-			id=self._packageID,
+			identifier=self._packageID,
 			columns={
 				"Filename": 500,
 				"Total": 100,
@@ -191,10 +191,10 @@ def renderlevel(tableBody: nodes.tbody, packageCoverage: PackageCoverage, level:
 
 		return table
 
-	def _CreateLegend(self, id: str, classes: Iterable[str]) -> List[nodes.Element]:
+	def _CreateLegend(self, identifier: str, classes: Iterable[str]) -> List[nodes.Element]:
 		rubric = nodes.rubric("", text="Legend")
 
-		table = nodes.table("", id=id, classes=classes)
+		table = nodes.table("", id=identifier, classes=classes)
 
 		tableGroup = nodes.tgroup(cols=2)
 		table += tableGroup
@@ -236,11 +236,11 @@ def run(self):
 		container = nodes.container()
 
 		if LegendPosition.Top in self._legend:
-			container += self._CreateLegend(id="legend1", classes=["doccov-legend"])
+			container += self._CreateLegend(identifier="legend1", classes=["doccov-legend"])
 
 		container += self._GenerateCoverageTable()
 
 		if LegendPosition.Bottom in self._legend:
-			container += self._CreateLegend(id="legend2", classes=["doccov-legend"])
+			container += self._CreateLegend(identifier="legend2", classes=["doccov-legend"])
 
 		return [container]

sphinx_reports/Sphinx.py

@@ -122,8 +122,8 @@ def _ParseLegendOption(self, optionName: str, default: Nullable[LegendPosition]
 		except KeyError as ex:
 			raise ReportExtensionError(f"{self.directiveName}::{optionName}: Value '{option}' is not a valid member of 'LegendPosition'.") from ex
 
-	def _PrepareTable(self, columns: Dict[str, int], id: str, classes: List[str]) -> Tuple[nodes.table, nodes.tgroup]:
-		table = nodes.table("", id=id, classes=classes)
+	def _PrepareTable(self, columns: Dict[str, int], identifier: str, classes: List[str]) -> Tuple[nodes.table, nodes.tgroup]:
+		table = nodes.table("", identifier=identifier, classes=classes)
 
 		tableGroup = nodes.tgroup(cols=(len(columns)))
 		table += tableGroup

sphinx_reports/Unittest.py

@@ -122,13 +122,13 @@ def _ConvertToColor(self, currentLevel, configKey):
 		for levelLimit, levelConfig in self._levels.items():
 			if (currentLevel * 100) < levelLimit:
 				return levelConfig[configKey]
-		else:
-			return self._levels[100][configKey]
+
+		return self._levels[100][configKey]
 
 	def _GenerateCoverageTable(self) -> nodes.table:
 		# Create a table and table header with 5 columns
 		table, tableGroup = self._PrepareTable(
-			id=self._packageID,
+			identifier=self._packageID,
 			columns={
 				"Filename": 500,
 				"Total": 100,
@@ -189,10 +189,10 @@ def renderlevel(tableBody: nodes.tbody, packageCoverage: PackageCoverage, level:
 
 		return table
 
-	def _CreateLegend(self, id: str, classes: Iterable[str]) -> List[nodes.Element]:
+	def _CreateLegend(self, identifier: str, classes: Iterable[str]) -> List[nodes.Element]:
 		rubric = nodes.rubric("", text="Legend")
 
-		table = nodes.table("", id=id, classes=classes)
+		table = nodes.table("", id=identifier, classes=classes)
 
 		tableGroup = nodes.tgroup(cols=2)
 		table += tableGroup
@@ -231,11 +231,11 @@ def run(self):
 		container = nodes.container()
 
 		if LegendPosition.Top in self._legend:
-			container += self._CreateLegend(id="legend1", classes=["doccov-legend"])
+			container += self._CreateLegend(identifier="legend1", classes=["doccov-legend"])
 
 		container += self._GenerateCoverageTable()
 
 		if LegendPosition.Bottom in self._legend:
-			container += self._CreateLegend(id="legend2", classes=["doccov-legend"])
+			container += self._CreateLegend(identifier="legend2", classes=["doccov-legend"])
 
 		return [container]

sphinx_reports/__init__.py

@@ -74,7 +74,7 @@ class ReportDomain(Domain):
 
 	* *None*
 
-  .. rubric:: Configuration variables
+	.. rubric:: Configuration variables
 
 	All configuration variables in :file:`conf.py` are prefixed with ``report_*``: