Run doxygen layout checker in prepare-commit script, when possible

Helps preventing useless CI wait like in here:
https://github.com/qgis/QGIS/actions/runs/6518501862/job/17703989815?pr=54934

Allow passing list of files to check to test_doxygen_layout.sh script

scripts/prepare_commit.sh

@@ -57,15 +57,34 @@ if [ -z "$MODIFIED" ]; then
   exit 0
 fi
 
+HAS_AG=false
+if command -v ag > /dev/null; then
+  HAS_AG=true
+fi
+
+HAS_UNBUFFER=false
+if command -v unbuffer > /dev/null; then
+  HAS_UNBUFFER=true
+fi
+
 # Run spell checker if requirements are met
-if ! command -v ag > /dev/null; then
+if test "$HAS_AG" != "true"; then
   echo "WARNING: the ag(1) executable was not found, spell checker could not run" >&2
-elif ! command -v unbuffer > /dev/null; then
+elif test "$HAS_UNBUFFER" != "true"; then
   echo "WARNING: the unbuffer(1) executable was not found, spell checker could not run" >&2
 else
   "${TOPLEVEL}"/scripts/spell_check/check_spelling.sh "$MODIFIED"
 fi
 
+# Run doxygen layout test if requirements are met
+if test "$HAS_AG" != "true"; then
+  echo "WARNING: the ag(1) executable was not found, doxygen layout checker could not run" >&2
+elif test "$HAS_UNBUFFER" != "true"; then
+  echo "WARNING: the unbuffer(1) executable was not found, doxygen layout checker could not run" >&2
+else
+  "${TOPLEVEL}"/tests/code_layout/test_doxygen_layout.sh $MODIFIED
+fi
+
 MODIFIED_SHELLFILES=$(echo "${MODIFIED}" | grep '\.sh$' || true)
 if [ -n "$MODIFIED_SHELLFILES" ]; then
   # Run shell checker if requirements are met

tests/code_layout/test_doxygen_layout.sh

@@ -1,15 +1,19 @@
 #!/usr/bin/env bash
 
+PATHS=${@-"$(cd $(dirname "$0")/../../ && pwd)"}
 
-# check that returns are placed before note and since
-output=$(unbuffer ag --noaffinity --file-search-regex '\.h$' --multiline '\\(note|since)[^\n]+(\n\s*\* [^\n]+)*\n\s*\* \\return' ${TRAVIS_BUILD_DIR} | tee /dev/stderr)
+echo "Checking doxygen layout in ${PATHS}"
+
+
+# check that \return(s) is placed before \note and \since
+output=$(unbuffer ag --noaffinity --file-search-regex '\.h$' --multiline '\\(note|since)[^\n]+(\n\s*\* [^\n]+)*\n\s*\* \\return' ${PATHS} | tee /dev/stderr)
 if [[ -n $output ]]; then
   echo -e "\n\x1B[31m*** Docstring computation: \\\return(s) should be placed before \\\note and \\since\x1B[0m"
   exit 1
 fi
 
 # check that \since and \deprecated are placed at the end of the command block
-output=$(unbuffer  ag --noaffinity --file-search-regex '\.h$' --multiline '(\\(deprecated|since)[^\n]+\n)+\s*\*[^\/](?!\s*\\(deprecated|since))' ${TRAVIS_BUILD_DIR} | tee /dev/stderr)
+output=$(unbuffer  ag --noaffinity --file-search-regex '\.h$' --multiline '(\\(deprecated|since)[^\n]+\n)+\s*\*[^\/](?!\s*\\(deprecated|since))' ${PATHS} | tee /dev/stderr)
 if [[ -n $output ]]; then
   echo -e "\n\x1B[31m*** Docstring computation: \\\deprecated and \\\since should be placed at the end of command blocks\x1B[0m"
   echo -e "To fix it, you may want to run (multiple times) at the top level directory:"
@@ -20,7 +24,7 @@ fi
 
 
 # code snippets command
-output=$(unbuffer ag --noaffinity --file-search-regex '\.h$' --multiline '~~~\{\.\w+\}' ${TRAVIS_BUILD_DIR} | tee /dev/stderr)
+output=$(unbuffer ag --noaffinity --file-search-regex '\.h$' --multiline '~~~\{\.\w+\}' ${PATHS} | tee /dev/stderr)
 if [[ -n $output ]]; then
   echo -e "\n\x1B[31m*** Docstring computation: code snippets should use \\\code{.xx} rather than ~~~{.xx} \x1B[0m"
   exit 1