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