partial better doxygen

Author: maureeungaro

ci/create_doxygen.sh

@@ -1,89 +1,148 @@
-#!/bin/zsh
-
-
-# Purpose: creates a doxyfile using the doxygen -g command to get the latest doxygen goodies)
-# The replace each line with the ones shown below
-
-echo " Creating System Doxyfile "
-doxygen -g &> /dev/null
-
-cp Doxyfile DoxyfilePure
-class=$1
-
-
-# painfully, manually doing these, but we HAVE TO
-# Note: keep STRIP_CODE_COMMENTS (refers just to doxygen comments) and SOURCE_TOOLTIPS to yes to make browing more readable
-sed -i "s/PROJECT_NAME           = \"My Project\"/PROJECT_NAME  = \"$class\"/g"                     Doxyfile
-sed -i 's/REPEAT_BRIEF           = YES/REPEAT_BRIEF           = NO/g'                               Doxyfile
-sed -i 's/OPTIMIZE_OUTPUT_FOR_C  = NO/OPTIMIZE_OUTPUT_FOR_C   = YES/g'                              Doxyfile
-sed -i 's/BUILTIN_STL_SUPPORT    = NO/BUILTIN_STL_SUPPORT     = YES/g'                              Doxyfile
-#sed -i 's/SHOW_INCLUDE_FILES     = YES/SHOW_INCLUDE_FILES     = NO/g'                               Doxyfile
-#sed -i 's/SHOW_FILES             = YES/SHOW_FILES             = NO/g'                               Doxyfile
-sed -i 's/EXTRACT_ALL            = NO/EXTRACT_ALL            = YES/g'                               Doxyfile
-sed -i 's/SOURCE_BROWSER         = NO/SOURCE_BROWSER          = YES/g'                              Doxyfile
-sed -i 's/RECURSIVE              = NO/RECURSIVE               = YES/g'                              Doxyfile
-sed -i 's/HTML_COLORSTYLE_HUE    = 220/HTML_COLORSTYLE_HUE    = 200/g'                              Doxyfile
-sed -i 's/HTML_COLORSTYLE_SAT    = 100/HTML_COLORSTYLE_SAT    = 240/g'                              Doxyfile
-sed -i 's/HTML_COLORSTYLE_GAMMA  = 80/HTML_COLORSTYLE_GAMMA   = 190/g'                              Doxyfile
-sed -i 's/HTML_DYNAMIC_MENUS     = YES/HTML_DYNAMIC_MENUS     = YES/g'                              Doxyfile
-sed -i 's/GENERATE_TREEVIEW      = NO/GENERATE_TREEVIEW       = YES/g'                              Doxyfile
-sed -i 's/FORMULA_FONTSIZE       = 10/FORMULA_FONTSIZE        = 14/g'                               Doxyfile
-sed -i 's/DOT_FONTNAME           = Helvetica/DOT_FONTNAME     = Avenir/g'                           Doxyfile
-sed -i 's/DOT_FONTSIZE           = 10/DOT_FONTSIZE            = 16/g'                               Doxyfile
-sed -i 's/TEMPLATE_RELATIONS     = NO/TEMPLATE_RELATIONS      = YES/g'                              Doxyfile
-sed -i 's/GENERATE_LATEX         = YES/GENERATE_LATEX         = NO/g'                               Doxyfile
-sed -i 's/HAVE_DOT               = NO/HAVE_DOT                = YES/g'                              Doxyfile
-sed -i 's/UML_LOOK               = NO/UML_LOOK                = YES/g'                              Doxyfile
-sed -i 's/EXCLUDE                =/EXCLUDE                    = README.md .git/g'                   Doxyfile
-sed -i 's/QUIET                  = NO/QUIET                   = YES/g'                              Doxyfile
-sed -i 's/HIDE_FRIEND_COMPOUNDS  = NO/HIDE_FRIEND_COMPOUNDS   = YES/g'                              Doxyfile
-sed -i "s/HTML_EXTRA_STYLESHEET  =/HTML_EXTRA_STYLESHEET      = ..\/mydoxygen.css/g"                 Doxyfile
-sed -i 's/PREDEFINED             =/PREDEFINED                 = DOXYGEN_SHOULD_SKIP_THIS/g'         Doxyfile
-
-
-# painfully removing the individual patterns
-sed -i  '/*.hpp \\/d'      Doxyfile
-sed -i  '/*.java \\/d'     Doxyfile
-sed -i  '/*.ii \\/d'       Doxyfile
-sed -i  '/*.ixx \\/d'      Doxyfile
-sed -i  '/*.ipp \\/d'      Doxyfile
-sed -i  '/*.i++ \\/d'      Doxyfile
-sed -i  '/*.inl \\/d'      Doxyfile
-sed -i  '/*.cs \\/d'       Doxyfile
-sed -i  '/*.d \\/d'        Doxyfile
-sed -i  '/*.m \\/d'        Doxyfile
-sed -i  '/*.doc \\/d'      Doxyfile
-sed -i  '/*.txt \\/d'      Doxyfile
-sed -i  '/*.f \\/d'        Doxyfile
-sed -i  '/*.for \\/d'      Doxyfile
-sed -i  '/*.vhd \\/d'      Doxyfile
-sed -i  '/*.ucf \\/d'      Doxyfile
-sed -i  '/*.md \\/d'       Doxyfile
-sed -i  '/*.mm \\/d'       Doxyfile
-sed -i  '/*.dox \\/d'      Doxyfile
-sed -i  '/*.f90 \\/d'      Doxyfile
-sed -i  '/*.f95 \\/d'      Doxyfile
-sed -i  '/*.f03 \\/d'      Doxyfile
-sed -i  '/*.f08 \\/d'      Doxyfile
-sed -i  '/*.markdown \\/d' Doxyfile
-sed -i  '/*.tcl \\/d'      Doxyfile
-sed -i  '/*.vhdl \\/d'     Doxyfile
-sed -i  '/*.qsf \\/d'      Doxyfile
-sed -i  '/*.php \\/d'      Doxyfile
-sed -i  '/*.php4 \\/d'     Doxyfile
-sed -i  '/*.php5 \\/d'     Doxyfile
-sed -i  '/*.phtml \\/d'    Doxyfile
-sed -i  '/*.idl \\/d'      Doxyfile
-sed -i  '/*.ddl \\/d'      Doxyfile
-sed -i  '/*.odl \\/d'      Doxyfile
-
-rm -f Doxyfilebackup
-
-toCheck=(PROJECT_NAME OPTIMIZE_OUTPUT_FOR_C BUILTIN_STL_SUPPORT SHOW_FILES HTML_COLORSTYLE_GAMMA QUIET)
-echo " "Doxyfile Main changes:
-echo
-for l in $toCheck
-do
-	setting=$(grep "$l" Doxyfile | grep -v "#")
-	echo "  - "$setting
-done
+#!/usr/bin/env zsh
+# Purpose:
+#   - Generate an up-to-date base Doxyfile from `doxygen -g` (cached per doxygen version)
+#   - Sanitize that base deterministically on every run (fixes template multi-line lists)
+#   - Emit a tiny per-module Doxyfile that @INCLUDEs that sanitized base
+#
+# Usage:
+#   ./ci/create_doxygen.sh <module_name>
+
+set -euo pipefail
+
+die() { print -u2 -- "ERROR: $*"; exit 2; }
+
+(( $# == 1 )) || die "Usage: $0 <module_name>"
+mod="$1"
+
+script_dir="${0:A:h}"
+cache_dir="$script_dir/doxygen/.cache"
+mkdir -p "$cache_dir"
+
+base_pure="$cache_dir/Doxyfile.pure"
+base_file="$cache_dir/Doxyfile.base"
+ver_file="$cache_dir/doxygen.version"
+
+doxver="$(doxygen --version)"
+
+# Portable in-place sed (BSD/macOS vs GNU)
+inplace_sed() {
+  local expr="$1"
+  local file="$2"
+  if sed --version >/dev/null 2>&1; then
+    sed -i "$expr" "$file"
+  else
+    sed -i '' "$expr" "$file"
+  fi
+}
+
+
+# Replace a doxygen list key that may be written as a multi-line block:
+#   KEY = *.a \
+#         *.b \
+# with a single-line canonical:
+#   KEY = value
+#
+# We remove the KEY line and its following "indented *..." continuation lines,
+# then append the canonical KEY line. Appending is semantically fine for doxygen.
+replace_doxy_list_key_single_line() {
+  local file="$1"
+  local key="$2"
+  local value="$3"
+
+  # Remove existing KEY line + template continuation lines that follow it.
+  awk -v key="^"key"[[:space:]]*=" '
+    BEGIN{skip=0}
+    $0 ~ key { skip=1; next }                   # drop the KEY = ... line
+    skip && $0 ~ /^[[:space:]]+\*/ { next }     # drop indented "*.ext \" lines
+    skip { skip=0 }                             # first non-continuation after block
+    { print }
+  ' "$file" > "$file.tmp" && mv "$file.tmp" "$file"
+
+  # Defensive: remove any stray KEY lines that might still exist (shouldn't).
+  if grep -qE "^${key}[[:space:]]*=" "$file"; then
+    inplace_sed "/^${key}[[:space:]]*=/d" "$file"
+  fi
+
+  print -- "${key}            = ${value}" >> "$file"
+}
+
+sanitize_base() {
+  local f="$1"
+
+  # ---- normalize base settings (small/stable list) ----
+  inplace_sed 's|^REPEAT_BRIEF[[:space:]]*=.*|REPEAT_BRIEF             = NO|g' "$f"
+  inplace_sed 's|^OPTIMIZE_OUTPUT_FOR_C[[:space:]]*=.*|OPTIMIZE_OUTPUT_FOR_C     = YES|g' "$f"
+  inplace_sed 's|^BUILTIN_STL_SUPPORT[[:space:]]*=.*|BUILTIN_STL_SUPPORT        = YES|g' "$f"
+  inplace_sed 's|^EXTRACT_ALL[[:space:]]*=.*|EXTRACT_ALL              = YES|g' "$f"
+  inplace_sed 's|^SOURCE_BROWSER[[:space:]]*=.*|SOURCE_BROWSER           = YES|g' "$f"
+  inplace_sed 's|^RECURSIVE[[:space:]]*=.*|RECURSIVE                = YES|g' "$f"
+  inplace_sed 's|^GENERATE_TREEVIEW[[:space:]]*=.*|GENERATE_TREEVIEW        = YES|g' "$f"
+  inplace_sed 's|^FORMULA_FONTSIZE[[:space:]]*=.*|FORMULA_FONTSIZE         = 14|g' "$f"
+  inplace_sed 's|^DOT_FONTNAME[[:space:]]*=.*|DOT_FONTNAME             = Avenir|g' "$f"
+  inplace_sed 's|^DOT_FONTSIZE[[:space:]]*=.*|DOT_FONTSIZE             = 16|g' "$f"
+  inplace_sed 's|^TEMPLATE_RELATIONS[[:space:]]*=.*|TEMPLATE_RELATIONS       = YES|g' "$f"
+  inplace_sed 's|^GENERATE_LATEX[[:space:]]*=.*|GENERATE_LATEX           = NO|g' "$f"
+  inplace_sed 's|^HAVE_DOT[[:space:]]*=.*|HAVE_DOT                = YES|g' "$f"
+  inplace_sed 's|^UML_LOOK[[:space:]]*=.*|UML_LOOK                = YES|g' "$f"
+  inplace_sed 's|^HIDE_FRIEND_COMPOUNDS[[:space:]]*=.*|HIDE_FRIEND_COMPOUNDS   = YES|g' "$f"
+  inplace_sed 's|^QUIET[[:space:]]*=.*|QUIET                   = YES|g' "$f"
+  inplace_sed 's|^WARNINGS[[:space:]]*=.*|WARNINGS                = YES|g' "$f"
+
+
+  replace_doxy_list_key_single_line "$f" "FILE_PATTERNS" \
+    "*.h *.hh *.hpp *.hxx *.c *.cc *.cpp *.cxx *.C *.H"
+
+  replace_doxy_list_key_single_line "$f" "EXCLUDE_PATTERNS" \
+    "*/.git/* */build/* */_build/* */cmake-build-*/* *.md *.markdown *.txt *.dox"
+
+  # Force stylesheet setting (delete any existing, then append)
+  inplace_sed '/^HTML_EXTRA_STYLESHEET[[:space:]]*=/d' "$f"
+  print -- 'HTML_EXTRA_STYLESHEET    = mydoxygen.css' >> "$f"
+
+  # Clear per-project knobs from the base (these will be set per-module)
+  inplace_sed '/^PROJECT_NAME[[:space:]]*=/d' "$f"
+  inplace_sed '/^INPUT[[:space:]]*=/d' "$f"
+  inplace_sed '/^OUTPUT_DIRECTORY[[:space:]]*=/d' "$f"
+  inplace_sed '/^HTML_OUTPUT[[:space:]]*=/d' "$f"
+  inplace_sed '/^GENERATE_TAGFILE[[:space:]]*=/d' "$f"
+  inplace_sed '/^TAGFILES[[:space:]]*=/d' "$f"
+}
+
+# ---- (re)generate base if missing or doxygen version changed ----
+need_regen=0
+if [[ ! -f "$base_pure" || ! -f "$base_file" || ! -f "$ver_file" ]]; then
+  need_regen=1
+elif [[ "$(cat "$ver_file")" != "$doxver" ]]; then
+  need_regen=1
+fi
+
+if (( need_regen )); then
+  print -- " [create_doxygen] Generating base for doxygen $doxver"
+  doxygen -g "$base_pure" >/dev/null 2>&1
+  cp -f "$base_pure" "$base_file"
+  print -- "$doxver" > "$ver_file"
+fi
+
+# Always sanitize (fixes stale/broken cache contents too)
+[[ -f "$base_file" ]] || die "Missing base file '$base_file'"
+sanitize_base "$base_file"
+
+# Emit tiny module Doxyfile that includes the generated base.
+# Use absolute path so it works regardless of where the module lives.
+base_abs="$base_file"
+
+cat > Doxyfile <<EOF
+@INCLUDE = $base_abs
+
+PROJECT_NAME              = "$mod"
+INPUT                     = .
+OUTPUT_DIRECTORY          = ../pages
+HTML_OUTPUT               = $mod
+GENERATE_TAGFILE          = ../pages/$mod/$mod.tag
+HTML_EXTRA_STYLESHEET     = mydoxygen.css
+
+# TAGFILES is injected by ci/doxygen.sh in pass 2
+EOF
+
+# Optional: keep local copy for debugging/inspection
+cp -f Doxyfile DoxyfilePure 2>/dev/null || true