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