[doc] Refine Doxygen 1.17 configuration

.github/workflows/macosmatrix.yml

@@ -54,7 +54,55 @@ jobs:
     #  if: runner.os=='macOS'
     - run: brew install catch2 # Issues with binary packages when cross-compiling...
       if: (runner.os=='macOS')&&(matrix.cfg.cross!=true)
-    - run: brew install graphviz ; brew install --formula doxygen ; python -m pip install --upgrade pip ; pip install --upgrade wheel setuptools sphinx breathe sphinx_rtd_theme sphinx-tabs sphinx-issues sphinx-reredirects furo sphinx-math-dollar sphinx_togglebutton sympy
+    # Doxygen 1.18.0 crashes when parsing Codac headers on macOS.
+    # Doxygen 1.16.1 ARM64 binaries require macOS 15: build from source on macOS 14.
+    - name: Install Doxygen 1.16.1
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        set -euo pipefail
+        case "${{ matrix.cfg.arch }}" in
+          arm64)  archive="doxygen-1.16.1.src.tar.gz" ;;
+          x86_64) archive="doxygen-1.16.1-mac-intel.zip" ;;
+          *) echo "Unsupported architecture" >&2; exit 1 ;;
+        esac
+        tmpdir="$(mktemp -d)"
+        trap 'rm -rf "$tmpdir"' EXIT
+
+        # Verify the archive using its official GitHub release SHA-256 digest.
+        expected_sha="$(
+          curl -fsSL --retry 3 \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            https://api.github.com/repos/doxygen/doxygen/releases/tags/Release_1_16_1 \
+          | python3 -c 'import json,sys; a=next(x for x in json.load(sys.stdin)["assets"] if x["name"]==sys.argv[1]); d=a["digest"]; assert d and d.startswith("sha256:") and len(d)==71; print(d[7:])' "$archive"
+        )"
+        curl -fsSL --retry 3 \
+          "https://github.com/doxygen/doxygen/releases/download/Release_1_16_1/${archive}" \
+          -o "$tmpdir/$archive"
+        echo "${expected_sha}  ${tmpdir}/${archive}" | shasum -a 256 -c
+
+        if [[ "${{ matrix.cfg.arch }}" == arm64 ]]; then
+          brew install ninja flex bison
+          mkdir "$tmpdir/src"
+          tar -xzf "$tmpdir/$archive" -C "$tmpdir/src"
+          export PATH="$(brew --prefix flex)/bin:$(brew --prefix bison)/bin:$PATH"
+          cmake -G Ninja -S "$tmpdir/src/doxygen-1.16.1" -B "$tmpdir/build" \
+            -DCMAKE_BUILD_TYPE=Release -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0 \
+            -Dbuild_wizard=OFF -Dbuild_doc=OFF -Duse_libclang=OFF
+          cmake --build "$tmpdir/build" --target doxygen --parallel 4
+          doxygen_bin="$tmpdir/build/bin/doxygen"
+        else
+          unzip -q "$tmpdir/$archive" -d "$tmpdir/unpacked"
+          doxygen_bin="$(find "$tmpdir/unpacked" -type f -name doxygen -print -quit)"
+        fi
+
+        mkdir -p "$RUNNER_TEMP/codac-doxygen-bin"
+        install -m 755 "$doxygen_bin" "$RUNNER_TEMP/codac-doxygen-bin/doxygen"
+        echo "$RUNNER_TEMP/codac-doxygen-bin" >> "$GITHUB_PATH"
+        "$RUNNER_TEMP/codac-doxygen-bin/doxygen" --version
+    - run: brew install graphviz ; python -m pip install --upgrade pip ; pip install --upgrade wheel setuptools sphinx breathe sphinx_rtd_theme sphinx-tabs sphinx-issues sphinx-reredirects furo sphinx-math-dollar sphinx_togglebutton sympy
       if: runner.os=='macOS'
     - run: |
         wget https://github.com/lebarsfa/ibex-lib/releases/download/ibex-2.8.9.20260819/ibex_${{ matrix.cfg.arch }}_${{ matrix.cfg.runtime }}.zip --no-check-certificate -nv

README.md

@@ -1,6 +1,12 @@
-# [Codac: constraint-programming for robotics](http://codac.io) [![Build Status](https://github.com/codac-team/codac/workflows/.github/workflows/tests.yml/badge.svg)](https://github.com/codac-team/codac/actions)
+# [Codac: constraint-programming for robotics](https://www.codac.io/)
 
-See the official website: http://codac.io
+[![Tests](https://github.com/codac-team/codac/actions/workflows/tests.yml/badge.svg?branch=codac2&event=push)](https://github.com/codac-team/codac/actions/workflows/tests.yml?query=branch%3Acodac2+event%3Apush)
+[![PyPI](https://img.shields.io/pypi/v/codac)](https://pypi.org/project/codac/)
+[![Documentation](https://img.shields.io/badge/docs-codac.io-blue)](https://www.codac.io/)
+[![License](https://img.shields.io/pypi/l/codac)](https://pypi.org/project/codac/)
+
+See the official website: https://www.codac.io
+[View all CI workflows on the codac2 branch](https://github.com/codac-team/codac/actions?query=branch%3Acodac2+event%3Apush)
 
 Codac (Catalog Of Domains And Contractors) is a C++/Python/Matlab library providing tools for interval computations and constraint programming over real numbers, trajectories and sets.
 It has numerous applications in parameter estimation, guaranteed integration, robot localization, and provides reliable outputs.

doc/CMakeLists.txt

@@ -41,10 +41,16 @@
         RESULT_VARIABLE DOXYGEN_RESULT
       )
       if(NOT DOXYGEN_RESULT EQUAL 0)
-        if(EXISTS "${CMAKE_BINARY_DIR}/doc/api/xml/index.xml")
-          message(WARNING "Doxygen exited with '${DOXYGEN_RESULT}' but generated XML output. Continuing so Python docstrings can still be generated.")
+        message(WARNING "Doxygen failed (exit code ${DOXYGEN_RESULT}). Retrying with full output:")
+        execute_process(
+          COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT}
+          RESULT_VARIABLE DOXYGEN_RETRY_RESULT
+        )
+        if(DOXYGEN_RETRY_RESULT EQUAL 0)
+          message(STATUS "Doxygen succeeded on the second attempt.")
         else()
-          message(FATAL_ERROR "Doxygen failed to generate the API documentation (exit code ${DOXYGEN_RESULT}), which is required for the Python docstrings. Doxygen errors: ${DOXYGEN_ERROR}")
+          # Do not accept partial XML output produced by a crashed Doxygen process.
+          message(FATAL_ERROR "Doxygen failed to generate the API documentation (first exit code ${DOXYGEN_RESULT}, retry exit code ${DOXYGEN_RETRY_RESULT}), which is required for the Python docstrings. Retry output is shown above. Initial Doxygen errors: ${DOXYGEN_ERROR}")
         endif()
       endif()
       add_custom_target(api COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT} OUTPUT_QUIET)

doc/api/Doxyfile.in

@@ -290,8 +290,8 @@ TAB_SIZE               = 4
 # with the commands \{ and \} for these it is advised to use the version @{ and
 # @} or use a double escape (\\{ and \\})
 
-ALIASES                = "license=@par License:" \
-                         "bugfixes=@par Bug fixes:"
+ALIASES                = "license=@par License: " \
+                         "bugfixes=@par Bug fixes: "
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
@@ -630,7 +630,7 @@ HIDE_UNDOC_CLASSES     = YES
 # option has no effect if EXTRACT_ALL is enabled.
 # The default value is: YES.
 
-HIDE_UNDOC_NAMESPACES  = YES
+HIDE_UNDOC_NAMESPACES  = NO
 
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all friend
 # declarations. If set to NO, these declarations will be included in the