From 1c91062dbcf47ec7b746b2c478affd447493c12f Mon Sep 17 00:00:00 2001
From: Wojciech Pietraszewski <wojciech.pietraszewski@codecoup.pl>
Date: Tue, 27 Feb 2024 16:05:33 +0100
Subject: [PATCH] ci: Add Doxygen Check workflow

This commit adds a new workflow for Doxygen Check to ensure documentation integrity.
The workflow verifies if the Doxygen output contains any warnings.
---
 .github/check_doxygen.py               | 115 +++++++++++++++++++++++++
 .github/workflows/compliance_check.yml |  19 +++-
 .rat-excludes                          |   1 +
 Doxyfile                               |   7 ++
 4 files changed, 141 insertions(+), 1 deletion(-)
 create mode 100755 .github/check_doxygen.py
 create mode 100644 Doxyfile

diff --git a/.github/check_doxygen.py b/.github/check_doxygen.py
new file mode 100755
index 0000000000..0f47a10bc0
--- /dev/null
+++ b/.github/check_doxygen.py
@@ -0,0 +1,115 @@
+#!/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 = [
+    "nimble/include/nimble/ble.h",
+]
+
+
+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:
+        return True
+    if filename in allowed:
+        return False
+    if re.search(r"nimble/host.*include.*", filename):
+        return False
+
+    return True
+
+
+def main() -> bool:
+    if len(sys.argv) > 1:
+        commit = sys.argv[1]
+    else:
+        commit = "HEAD"
+    if len(sys.argv) > 2:
+        upstream = sys.argv[2]
+    else:
+        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/compliance_check.yml b/.github/workflows/compliance_check.yml
index 9b2ee76315..ade32b220a 100644
--- a/.github/workflows/compliance_check.yml
+++ b/.github/workflows/compliance_check.yml
@@ -56,7 +56,24 @@ jobs:
              wget https://dlcdn.apache.org//creadur/apache-rat-0.16.1/apache-rat-0.16.1-bin.tar.gz
              tar zxf apache-rat-0.16.1-bin.tar.gz apache-rat-0.16.1/apache-rat-0.16.1.jar
              mv apache-rat-0.16.1/apache-rat-0.16.1.jar apache-rat.jar
-      - name: check licensing
+      - name: Check licensing
         shell: bash
         run: |
              ./repos/apache-mynewt-core/.github/check_license.py
+
+  style_doxygen:
+    name: Doxygen Style
+    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/.rat-excludes b/.rat-excludes
index f29a97eb1d..b0bf3e0977 100644
--- a/.rat-excludes
+++ b/.rat-excludes
@@ -18,6 +18,7 @@ uncrustify.cfg
 .style_ignored_dirs
 .mailmap
 requirements.txt
+Doxyfile
 
 # tinycrypt - BSD License.
 tinycrypt
diff --git a/Doxyfile b/Doxyfile
new file mode 100644
index 0000000000..35909d5383
--- /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