sphinx_reports.Common

Code coverage of sphinx_reports.common

# ==================================================================================================================== #
#            _     _                                           _                                                       #
#  ___ _ __ | |__ (_)_ __ __  __     _ __ ___ _ __   ___  _ __| |_ ___                                                 #
# / __| '_ \| '_ \| | '_ \\ \/ /____| '__/ _ \ '_ \ / _ \| '__| __/ __|                                                #
# \__ \ |_) | | | | | | | |>  <_____| | |  __/ |_) | (_) | |  | |_\__ \                                                #
# |___/ .__/|_| |_|_|_| |_/_/\_\    |_|  \___| .__/ \___/|_|   \__|___/                                                #
#     |_|                                    |_|                                                                       #
# ==================================================================================================================== #
# 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


@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"]

  @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}")

  @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")

  @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.

  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


@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.
  }