# ==================================================================================================================== #
# _ _ _ #
# ___ _ __ | |__ (_)_ __ __ __ _ __ ___ _ __ ___ _ __| |_ ___ #
# / __| '_ \| '_ \| | '_ \\ \/ /____| '__/ _ \ '_ \ / _ \| '__| __/ __| #
# \__ \ |_) | | | | | | | |> <_____| | | __/ |_) | (_) | | | |_\__ \ #
# |___/ .__/|_| |_|_|_| |_/_/\_\ |_| \___| .__/ \___/|_| \__|___/ #
# |_| |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2023-2024 Patrick Lehmann - Bötzingen, Germany #
# #
# Licensed under the Apache License, Version 2.0 (the "License"); #
# you may not use this file except in compliance with the License. #
# You may obtain a copy of the License at #
# #
# http://www.apache.org/licenses/LICENSE-2.0 #
# #
# Unless required by applicable law or agreed to in writing, software #
# distributed under the License is distributed on an "AS IS" BASIS, #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
# See the License for the specific language governing permissions and #
# limitations under the License. #
# #
# SPDX-License-Identifier: Apache-2.0 #
# ==================================================================================================================== #
#
"""
**A Sphinx domain providing directives to add reports to the Sphinx-based documentation.**
Supported reports:
* :ref:`DOCCOV`
* :ref:`CODECOV`
* :ref:`UNITTEST`
* :ref:`DEP`
"""
__author__ = "Patrick Lehmann"
__email__ = "Paebbels@gmail.com"
__copyright__ = "2023-2024, Patrick Lehmann"
__license__ = "Apache License, Version 2.0"
__version__ = "0.7.4"
__keywords__ = ["Python3", "Sphinx", "Extension", "Report", "doc-string", "interrogate"]
from hashlib import md5
from pathlib import Path
from typing import TYPE_CHECKING, Any, Tuple, Dict, Optional as Nullable, TypedDict, List, Callable
from docutils import nodes
from sphinx.addnodes import pending_xref
from sphinx.application import Sphinx
from sphinx.builders import Builder
from sphinx.config import Config
from sphinx.domains import Domain
from sphinx.environment import BuildEnvironment
from pyTooling.Decorators import export
from pyTooling.Common import readResourceFile
from sphinx.util.logging import getLogger
from sphinx_reports.Common import ReportExtensionError
from sphinx_reports import static as ResourcePackage
[docs]
@export
class ReportDomain(Domain):
"""
A Sphinx extension providing a ``report`` domain to integrate reports and summaries into a Sphinx-based documentation.
.. rubric:: New directives:
* :rst:dir:`report:code-coverage`
* :rst:dir:`report:code-coverage-legend`
* :rst:dir:`report:doc-coverage`
* :rst:dir:`report:doc-coverage-legend`
* :rst:dir:`report:dependency-table`
* :rst:dir:`report:unittest-summary`
.. rubric:: New roles:
* *None*
.. rubric:: New indices:
* *None*
.. rubric:: Configuration variables
All configuration variables in :file:`conf.py` are prefixed with ``report_*``:
* ``report_codecov_packages``
* ``report_doccov_packages``
* ``report_unittest_testsuites``
"""
name = "report" #: The name of this domain
label = "rpt" #: The label of this domain
dependencies: List[str] = [
] #: A list of other extensions this domain depends on.
from sphinx_reports.CodeCoverage import CodeCoverage, CodeCoverageLegend, ModuleCoverage
from sphinx_reports.DocCoverage import DocStrCoverage, DocCoverageLegend
from sphinx_reports.Dependency import DependencyTable
from sphinx_reports.Unittest import UnittestSummary
directives = {
"code-coverage": CodeCoverage,
"code-coverage-legend": CodeCoverageLegend,
"module-coverage": ModuleCoverage,
"doc-coverage": DocStrCoverage,
"doc-coverage-legend": DocCoverageLegend,
"dependency-table": DependencyTable,
"unittest-summary": UnittestSummary,
} #: A dictionary of all directives in this domain.
roles = {
# "design": DesignRole,
} #: A dictionary of all roles in this domain.
indices = [
# LibraryIndex,
] #: A list of all indices in this domain.
from sphinx_reports.CodeCoverage import CodeCoverageBase
from sphinx_reports.DocCoverage import DocCoverageBase
from sphinx_reports.Dependency import DependencyTable
from sphinx_reports.Unittest import UnittestSummary
configValues: Dict[str, Tuple[Any, str, Any]] = {
**CodeCoverageBase.configValues,
**DocCoverageBase.configValues,
**UnittestSummary.configValues,
**DependencyTable.configValues,
} #: A dictionary of all configuration values used by this domain. (name: (default, rebuilt, type))
del CodeCoverageBase
del CodeCoverage
del CodeCoverageLegend
del ModuleCoverage
del DocCoverageBase
del DocStrCoverage
del DocCoverageLegend
del DependencyTable
del UnittestSummary
initial_data = {
# "reports": {}
} #: A dictionary of all global data fields used by this domain.
# @property
# def Reports(self) -> Dict[str, Any]:
# return self.data["reports"]
[docs]
@staticmethod
def CheckConfigurationVariables(sphinxApplication: Sphinx, config: Config) -> None:
"""
Call back for Sphinx ``config-inited`` event.
This callback will verify configuration variables used by that domain.
.. seealso::
Sphinx *builder-inited* event
See https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
:param sphinxApplication: The Sphinx application.
:param config: Sphinx configuration parsed from ``conf.py``.
"""
from sphinx_reports.CodeCoverage import CodeCoverageBase
from sphinx_reports.DocCoverage import DocCoverageBase
from sphinx_reports.Unittest import UnittestSummary
checkConfigurations = (
CodeCoverageBase.CheckConfiguration,
DocCoverageBase.CheckConfiguration,
UnittestSummary.CheckConfiguration,
)
for checkConfiguration in checkConfigurations:
try:
checkConfiguration(sphinxApplication, config)
except ReportExtensionError as ex:
logger = getLogger(__name__)
logger.error(f"Caught {ex.__class__.__name__} when checking configuration variables.\n {ex}")
[docs]
@staticmethod
def AddCSSFiles(sphinxApplication: Sphinx) -> None:
"""
Call back for Sphinx ``builder-inited`` event.
This callback will copy the CSS file(s) to the build directory.
.. seealso::
Sphinx *builder-inited* event
See https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
:param sphinxApplication: The Sphinx application.
"""
# Create a new static path for this extension
staticDirectory = (Path(sphinxApplication.outdir) / "_report_static").resolve()
staticDirectory.mkdir(exist_ok=True)
sphinxApplication.config.html_static_path.append(str(staticDirectory))
# Read the CSS content from package resources and hash it
cssFilename = "sphinx-reports.css"
cssContent = readResourceFile(ResourcePackage, cssFilename)
# Compute md5 hash of CSS file
hash = md5(cssContent.encode("utf8")).hexdigest()
# Write the CSS file into output directory
cssFile = staticDirectory / f"sphinx-reports.{hash}.css"
sphinxApplication.add_css_file(cssFile.name)
if not cssFile.exists():
# Purge old CSS files
for file in staticDirectory.glob("*.css"):
file.unlink()
# Write CSS content
cssFile.write_text(cssContent, encoding="utf8")
[docs]
@staticmethod
def ReadReports(sphinxApplication: Sphinx) -> None:
"""
Call back for Sphinx ``builder-inited`` event.
This callback will read the linked report files
.. seealso::
Sphinx *builder-inited* event
See https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
:param sphinxApplication: The Sphinx application.
"""
from sphinx_reports.CodeCoverage import CodeCoverageBase
from sphinx_reports.Unittest import UnittestSummary
CodeCoverageBase.ReadReports(sphinxApplication)
UnittestSummary.ReadReports(sphinxApplication)
callbacks: Dict[str, List[Callable]] = {
"config-inited": [CheckConfigurationVariables], # (app, config)
"builder-inited": [AddCSSFiles, ReadReports], # (app)
} #: A dictionary of all events/callbacks <https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events>`__ used by this domain.
[docs]
def resolve_xref(
self,
env: BuildEnvironment,
fromdocname: str,
builder: Builder,
typ: str,
target: str,
node: pending_xref,
contnode: nodes.Element
) -> Nullable[nodes.Element]:
raise NotImplementedError()
if TYPE_CHECKING:
class setup_ReturnType(TypedDict):
version: str
env_version: int
parallel_read_safe: bool
parallel_write_safe: bool
[docs]
@export
def setup(sphinxApplication: Sphinx) -> "setup_ReturnType":
"""
Extension setup function registering the ``report`` domain in Sphinx.
It will execute these steps:
* register domains, directives and roles.
* connect events (register callbacks)
* register configuration variables for :file:`conf.py`
:param sphinxApplication: The Sphinx application.
:return: Dictionary containing the extension version and some properties.
"""
sphinxApplication.add_domain(ReportDomain)
# Register callbacks
for eventName, callbacks in ReportDomain.callbacks.items():
for callback in callbacks:
sphinxApplication.connect(eventName, callback)
# Register configuration options supported/needed in Sphinx's 'conf.py'
for configName, (configDefault, configRebuilt, configTypes) in ReportDomain.configValues.items():
sphinxApplication.add_config_value(f"{ReportDomain.name}_{configName}", configDefault, configRebuilt, configTypes)
return {
"version": __version__, # version of the extension
"env_version": int(__version__.split(".")[0]), # version of the data structure stored in the environment
'parallel_read_safe': False, # Not yet evaluated, thus false
'parallel_write_safe': True, # Internal data structure is used read-only, thus no problems will occur by parallel writing.
}