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

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

.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

.rat-excludes

@@ -18,6 +18,7 @@ uncrustify.cfg
 .style_ignored_dirs
 .mailmap
 requirements.txt
+Doxyfile
 
 # tinycrypt - BSD License.
 tinycrypt

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