This is an automated email from the ASF dual-hosted git repository. janc pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/mynewt-core.git
commit 95ca335a8a28d3b99a1d72dec549cefa836979d4 Author: Wojciech Pietraszewski <[email protected]> AuthorDate: Mon Jun 24 14:46:51 2024 +0200 ci: Add `Doxygen Check` job to the compliance workflow This pull request adds a new check to the CI pipeline to ensure documentation integrity. The script verifies if the Doxygen output contains any warnings. --- .github/check_doxygen.py | 106 +++++++++++++++++++++++++++++++++ .github/workflows/check_compliance.yml | 17 ++++++ Doxyfile | 7 +++ 3 files changed, 130 insertions(+) diff --git a/.github/check_doxygen.py b/.github/check_doxygen.py new file mode 100755 index 000000000..24872e4f5 --- /dev/null +++ b/.github/check_doxygen.py @@ -0,0 +1,106 @@ +#!/usr/bin/env python3 + +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you 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. +# + +import os +import re +import subprocess +import sys +from pathlib import Path + +TMP_FOLDER = "/tmp/doxygen_check" +WARN_FILE_NAME = "warnings.log" +allowed_files = [] + + +def run_cmd(cmd: str) -> list[str]: + out = subprocess.check_output(cmd, text=True, shell=True) + return out.splitlines() + + +def run_cmd_no_check(cmd: str) -> list[str]: + out = subprocess.run(cmd, text=True, shell=True, stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL).stdout + return out.splitlines() + + +def is_ignored(filename: str, allowed: list[str]) -> bool: + if Path(filename).suffix != ".h" or "priv" in filename or "arch" in filename: + return True + if filename in allowed: + return False + if re.search(r"kernel/os/include/os/.*", filename): + return False + + return True + + +def main() -> bool: + commit = "HEAD" + upstream = "origin/master" + mb = run_cmd(f"git merge-base {upstream} {commit}") + upstream = mb[0] + + results_ok = [] + results_fail = [] + results_ign = [] + + os.makedirs(Path(TMP_FOLDER, WARN_FILE_NAME).parent, mode=0o755, + exist_ok=True) + + files = run_cmd(f"git diff --diff-filter=AM --name-only {upstream} {commit}") + for fname in files: + if is_ignored(fname, allowed_files): + results_ign.append(fname) + continue + + os.environ['DOXYGEN_INPUT'] = fname + try: + run_cmd_no_check("doxygen") + + except subprocess.CalledProcessError as e: + print(f"\033[31m[FAIL] {e.returncode}\033[0m") + return False + + with open(os.path.join(TMP_FOLDER, WARN_FILE_NAME)) as warn_log: + warnings = warn_log.read() + if len(warnings) == 0: + results_ok.append(fname) + else: + results_fail.append((fname, warnings)) + + for fname in results_ign: + print(f"\033[90m[ NA ] {fname}\033[0m") + for fname in results_ok: + print(f"\033[32m[ OK ] {fname}\033[0m") + for fname, warnings in results_fail: + print(f"\033[31m[FAIL] {fname}\033[0m") + print(warnings) + + if len(results_fail) > 0: + print(f"\033[31mYour code has documentation style problems, see the logs " + f"for details.\033[0m") + + return len(results_fail) == 0 + + +if __name__ == "__main__": + if not main(): + sys.exit(1) diff --git a/.github/workflows/check_compliance.yml b/.github/workflows/check_compliance.yml index a3c3752f5..886c300a9 100644 --- a/.github/workflows/check_compliance.yml +++ b/.github/workflows/check_compliance.yml @@ -52,3 +52,20 @@ jobs: - name: check licensing run: | .github/check_license.py + + doxygen_check: + name: Doxygen Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Install Dependencies + shell: bash + run: | + sudo apt-get update + sudo apt-get install -y doxygen + - name: Check Doxygen + shell: bash + run: | + .github/check_doxygen.py diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 000000000..35909d538 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,7 @@ +WARN_NO_PARAMDOC = YES +WARN_LOGFILE = /tmp/doxygen_check/warnings.log +INPUT = $(DOXYGEN_INPUT) +GENERATE_HTML = NO +GENERATE_LATEX = NO +MACRO_EXPANSION = YES +WARN_FORMAT = $line: $text
