Skip to content

File doxyrun.py

File List > mkdoxy > doxyrun.py

Go to the documentation of this file

import hashlib
import logging
import os
import shutil
import re

from pathlib import Path, PurePath
from subprocess import PIPE, Popen
from typing import Optional

log: logging.Logger = logging.getLogger("mkdocs")


class DoxygenRun:
    """! Class for running Doxygen.
    @details This class is used to run Doxygen and parse the XML output.
    """

    def __init__(
        self,
        doxygenBinPath: str,
        doxygenSource: str,
        tempDoxyFolder: str,
        doxyCfgNew,
        doxyConfigFile: Optional[str] = None,
    ):
        """! Constructor.
        Default Doxygen config options:

        - INPUT: <doxygenSource>
        - OUTPUT_DIRECTORY: <tempDoxyFolder>
        - DOXYFILE_ENCODING: UTF-8
        - GENERATE_XML: YES
        - RECURSIVE: YES
        - EXAMPLE_PATH: examples
        - SHOW_NAMESPACES: YES
        - GENERATE_HTML: NO
        - GENERATE_LATEX: NO

        @details
        @param doxygenBinPath: (str) Path to the Doxygen binary.
        @param doxygenSource: (str) Source files for Doxygen.
        @param tempDoxyFolder: (str) Temporary folder for Doxygen.
        @param doxyConfigFile: (str) Path to a Doxygen config file.
        @param doxyCfgNew: (dict) New Doxygen config options that will be added to the default config (new options will overwrite default options)
        """  # noqa: E501

        if not self.is_doxygen_valid_path(doxygenBinPath):
            raise DoxygenBinPathNotValid(
                f"Invalid Doxygen binary path: {doxygenBinPath}\n"
                f"Make sure Doxygen is installed and the path is correct.\n"
                f"Look at https://mkdoxy.kubaandrysek.cz/usage/advanced/#configure-custom-doxygen-binary."
            )

        self.doxygenBinPath: str = doxygenBinPath
        self.doxygenSource: str = doxygenSource
        self.tempDoxyFolder: str = tempDoxyFolder
        self.doxyConfigFile: Optional[str] = doxyConfigFile
        self.hashFileName: str = "hashChanges.yaml"
        self.hashFilePath: PurePath = PurePath.joinpath(Path(self.tempDoxyFolder), Path(self.hashFileName))
        self.doxyCfg: dict = self.setDoxyCfg(doxyCfgNew)

    def setDoxyCfg(self, doxyCfgNew: dict) -> dict:
        """! Set the Doxygen configuration.
        @details If a custom Doxygen config file is provided, it will be used. Otherwise, default options will be used.
        @details Order of application of parameters:
        @details 1. Custom Doxygen config file
        @details 2. If not provided, default options - in documentation
        @details 3. New Doxygen config options from mkdocs.yml
        @details 3. Overwrite INPUT and OUTPUT_DIRECTORY with the provided values for correct plugin operation.

        @details Overwrite options description:
        @details - INPUT: <doxygenSource>
        @details - OUTPUT_DIRECTORY: <tempDoxyFolder>

        @details Default Doxygen config options:
        @details - DOXYFILE_ENCODING: UTF-8
        @details - GENERATE_XML: YES
        @details - RECURSIVE: YES
        @details - EXAMPLE_PATH: examples
        @details - SHOW_NAMESPACES: YES
        @details - GENERATE_HTML: NO
        @details - GENERATE_LATEX: NO
        @param doxyCfgNew: (dict) New Doxygen config options that will be
         added to the default config (new options will overwrite default options)
        @return: (dict) Doxygen configuration.
        """
        doxyCfg = {}

        if self.doxyConfigFile is not None and self.doxyConfigFile != "":
            try:
                with open(self.doxyConfigFile, "r") as file:
                    doxyCfg.update(self.str2dox_dict(file.read()))
            except FileNotFoundError as e:
                raise DoxygenCustomConfigNotFound(
                    f"Custom Doxygen config file not found: {self.doxyConfigFile}\n"
                    f"Make sure the path is correct."
                    f"Look at https://mkdoxy.kubaandrysek.cz/usage/advanced/#configure-custom-doxygen-configuration-file."
                ) from e
        else:
            doxyCfg = {
                "DOXYFILE_ENCODING": "UTF-8",
                "GENERATE_XML": "YES",
                "RECURSIVE": "YES",
                "EXAMPLE_PATH": "examples",
                "SHOW_NAMESPACES": "YES",
                "GENERATE_HTML": "NO",
                "GENERATE_LATEX": "NO",
            }

        doxyCfg.update(doxyCfgNew)
        doxyCfg["INPUT"] = self.doxygenSource
        doxyCfg["OUTPUT_DIRECTORY"] = self.tempDoxyFolder
        return doxyCfg

    def is_doxygen_valid_path(self, doxygen_bin_path: str) -> bool:
        """! Check if the Doxygen binary path is valid.
        @details Accepts a full path or just 'doxygen' if it exists in the system's PATH.
        @param doxygen_bin_path: (str) The path to the Doxygen binary or just 'doxygen'.
        @return: (bool) True if the Doxygen binary path is valid, False otherwise.
        """
        # If the path is just 'doxygen', search for it in the system's PATH
        if doxygen_bin_path.lower() == "doxygen":
            return shutil.which("doxygen") is not None

        # Use pathlib to check if the provided full path is a file and executable
        path = Path(doxygen_bin_path)
        return path.is_file() and os.access(path, os.X_OK)

    # Source of dox_dict2str: https://xdress-fabio.readthedocs.io/en/latest/_modules/xdress/doxygen.html#XDressPlugin
    def dox_dict2str(self, dox_dict: dict) -> str:
        """! Convert a dictionary to a string that can be written to a doxygen config file.
        @details
        @param dox_dict: (dict) Dictionary to convert.
        @return: (str) String that can be written to a doxygen config file.
        """
        s = ""
        new_line = "{option} = {value}\n"
        for key, value in dox_dict.items():
            if value is True:
                _value = "YES"
            elif value is False:
                _value = "NO"
            else:
                _value = value

            s += new_line.format(option=key.upper(), value=_value)

        # Don't need an empty line at the end
        return s.strip()

    def str2dox_dict(self, dox_str: str) -> dict:
        """! Convert a string from a doxygen config file to a dictionary.
        @details
        @param dox_str: (str) String from a doxygen config file.
        @return: (dict) Dictionary.
        """
        dox_dict = {}
        dox_str = re.sub(r"\\\s*\n\s*", "", dox_str)
        pattern = r"^\s*([^=\s]+)\s*(=|\+=)\s*(.*)$"

        try:
            for line in dox_str.split("\n"):
                if line.strip() == "" or line.startswith("#"):
                    continue
                match = re.match(pattern, line)
                if not match:
                    raise DoxygenCustomConfigNotValid(
                        f"Invalid line: '{line}'"
                        f"In custom Doxygen config file: {self.doxyConfigFile}\n"
                        f"Make sure the file is in standard Doxygen format."
                        f"Look at https://mkdoxy.kubaandrysek.cz/usage/advanced/."
                    )
                key, operator, value = match.groups()
                value = value.strip()
                if operator == "=":
                    if value == "YES":
                        dox_dict[key] = True
                    elif value == "NO":
                        dox_dict[key] = False
                    else:
                        dox_dict[key] = value
                if operator == "+=":
                    dox_dict[key] = f"{dox_dict[key]} {value}"
        except ValueError as e:
            raise DoxygenCustomConfigNotValid(
                f"Invalid custom Doxygen config file: {self.doxyConfigFile}\n"
                f"Make sure the file is in standard Doxygen format."
                f"Look at https://mkdoxy.kubaandrysek.cz/usage/advanced/."
            ) from e
        return dox_dict

    @staticmethod
    def _config_paths(value: str) -> list[Path]:
        """Split Doxygen's whitespace/double-quoted paths without shell execution."""
        expanded = re.sub(r"\$\((\w+)\)", lambda match: os.environ.get(match.group(1), ""), value)
        return [Path(first or second) for first, second in re.findall(r'"([^"]*)"|(\S+)', expanded) if first or second]

    def _input_hash(self) -> str:
        digest = hashlib.sha256()
        digest.update(self.dox_dict2str(self.doxyCfg).encode("utf-8"))
        inputs: set[Path] = set()
        roots = self._config_paths(self.doxygenSource)
        roots.extend(self._config_paths(str(self.doxyCfg.get("IMAGE_PATH", ""))))
        output = Path(self.tempDoxyFolder).resolve()
        for root in roots:
            paths = [root] if root.is_file() else root.rglob("*")
            for path in paths:
                if path.is_file() and not path.resolve().is_relative_to(output):
                    inputs.add(path.resolve())
        for path in sorted(inputs):
            name = str(path).encode("utf-8")
            digest.update(len(name).to_bytes(8, "big"))
            digest.update(name)
            digest.update(path.stat().st_size.to_bytes(8, "big"))
            with path.open("rb") as source:
                for chunk in iter(lambda: source.read(65536), b""):
                    digest.update(chunk)
        return digest.hexdigest()

    def _cache_matches(self, digest: str) -> bool:
        if not (Path(self.getOutputFolder()) / "index.xml").is_file():
            return False
        try:
            return Path(self.hashFilePath).read_text(encoding="utf-8") == digest
        except FileNotFoundError:
            return False

    def hasChanged(self) -> bool:
        """Check source, image and effective configuration inputs without changing the cache."""
        return not self._cache_matches(self._input_hash())

    def run(self):
        """! Run Doxygen with the current configuration using the Popen class.
        @details
        """
        doxyBuilder = Popen(
            [self.doxygenBinPath, "-"],
            stdout=PIPE,
            stdin=PIPE,
            stderr=PIPE,
        )
        stdout, stderr = doxyBuilder.communicate(self.dox_dict2str(self.doxyCfg).encode("utf-8"))
        if doxyBuilder.returncode != 0:
            raise RuntimeError(
                f"Doxygen failed with exit status {doxyBuilder.returncode}\n"
                f"stdout:\n{stdout.decode('utf-8', errors='replace')}\n"
                f"stderr:\n{stderr.decode('utf-8', errors='replace')}"
            )

    def checkAndRun(self):
        """! Check if the source files have changed since the last run and run Doxygen if they have.
        @details
        @return: (bool) True if Doxygen was run.
        """
        digest = self._input_hash()
        if self._cache_matches(digest):
            return False
        # No hash may certify old/partial output after a failed or interrupted run.
        Path(self.hashFilePath).unlink(missing_ok=True)
        index = Path(self.getOutputFolder()) / "index.xml"
        index.unlink(missing_ok=True)
        self.run()
        if not index.is_file():
            raise RuntimeError(f"Doxygen did not create the required XML index: {index}")
        Path(self.hashFilePath).write_text(digest, encoding="utf-8")
        return True

    def getOutputFolder(self) -> PurePath:
        """! Get the path to the XML output folder.
        @details
        @return: (PurePath) Path to the XML output folder.
        """
        return Path.joinpath(Path(self.tempDoxyFolder), Path("xml"))


# not valid path exception
class DoxygenBinPathNotValid(Exception):
    pass


class DoxygenCustomConfigNotFound(Exception):
    pass


class DoxygenCustomConfigNotValid(Exception):
    pass