added doc CI job

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - '**'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  doxygen:
+    name: Doxygen (ubuntu-24.04)
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          DEBIAN_FRONTEND=noninteractive
+          sudo apt-get update
+          sudo apt-get install -y \
+            doxygen \
+            cmake \
+            libopencv-dev \
+            libpcl-dev \
+            libyaml-cpp-dev \
+            git
+
+      - name: Configure CMake (export headers for Doxygen)
+        run: |
+          cmake -B ${{ github.workspace }}/build-docs \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_TESTING=OFF \
+            -DBUILD_APP=OFF \
+            -DBUILD_TOOLS=OFF \
+            -DBUILD_EXAMPLES=OFF \
+            -DWITH_QT=OFF \
+            -DWITH_PYTHON=OFF \
+            -DWITH_CERES=OFF \
+            -DWITH_G2O=OFF \
+            -DWITH_GTSAM=OFF \
+            -DWITH_MRPT=OFF \
+            -DWITH_VERTIGO=OFF \
+            -DWITH_CVSBA=OFF \
+            -DWITH_POINTMATCHER=OFF \
+            -DWITH_CCCORELIB=OFF \
+            -DWITH_OPEN3D=OFF \
+            -DWITH_LOAM=OFF \
+            -DWITH_FLOAM=OFF \
+            -DWITH_LIOSAM=OFF \
+            -DWITH_FLYCAPTURE2=OFF \
+            -DWITH_ZED=OFF \
+            -DWITH_ZEDOC=OFF \
+            -DWITH_REALSENSE=OFF
+
+      - name: Generate Doxygen HTML
+        run: doxygen Doxyfile
+
+      - name: Upload Doxygen HTML artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: doxygen-html
+          path: doc/html
+          retention-days: 14

.github/workflows/rosdoc.yml

@@ -0,0 +1,57 @@
+name: ROS Documentation
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - '**'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  rosdoc:
+    name: rosdoc2 (jazzy)
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Setup ROS2
+        run: |
+          sudo apt install software-properties-common
+          sudo add-apt-repository universe
+          sudo apt update && sudo apt install curl -y
+          export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\" '{print $4}')
+          curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
+          sudo apt install /tmp/ros2-apt-source.deb
+          sudo apt update
+
+      - uses: ros-tooling/[email protected]
+        with:
+          required-ros-distributions: jazzy
+
+      - uses: actions/checkout@v4
+
+      - name: Install documentation tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-rosdoc2 doxygen graphviz
+
+      - name: Generate Sphinx documentation (rosdoc2)
+        run: |
+          # Do not source a colcon workspace (rosdoc2 known issue #66).
+          source /opt/ros/jazzy/setup.bash
+          rosdoc2 build --package-path "${{ github.workspace }}"
+
+      - name: Upload ROS documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: rosdoc2-html
+          path: docs_output/rtabmap
+          retention-days: 14

.gitignore

@@ -12,10 +12,19 @@ compile_flags.txt
 tags
 build_*
 *.bak
+build-*
 
 # Coverage (coverage-report.sh / .github/workflows/coverage.yml)
-build-coverage/
 coverage-html/
 lcov.info
 *.gcda
 *.gcno
+
+# Doxygen (docs-report.sh / .github/workflows/docs.yml)
+doc/
+.doxygen-input
+
+# rosdoc2 (rosdoc-report.sh / .github/workflows/rosdoc.yml)
+cross_reference/
+docs_build/
+docs_output/

Doxyfile

@@ -854,7 +854,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = corelib/include build/corelib/src/include
+INPUT                  = corelib/include utilite/include build-docs/corelib/src/include
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs-report.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Generate Doxygen HTML at doc/html/index.html
+# Run from anywhere; defaults: build dir = build-docs, output = doc/html/
+# Override build tree: DOCS_BUILD_DIR=/path/to/build ./docs-report.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BUILD_DIR="${DOCS_BUILD_DIR:-$ROOT/build-docs}"
+HTML_DIR="${DOCS_HTML_DIR:-$ROOT/doc/html}"
+DOXY_INPUT_OVERRIDE="${DOCS_DOXY_INPUT:-$ROOT/.doxygen-input}"
+
+need_cmd() {
+	command -v "$1" >/dev/null 2>&1 || {
+		echo "Error: required command not found: $1" >&2
+		exit 1
+	}
+}
+
+need_cmd cmake
+need_cmd doxygen
+need_cmd gcc
+
+configure_docs_build() {
+	cmake -B "$BUILD_DIR" \
+		-DCMAKE_BUILD_TYPE=Release \
+		-DBUILD_TESTING=OFF \
+		-DBUILD_APP=OFF \
+		-DBUILD_TOOLS=OFF \
+		-DBUILD_EXAMPLES=OFF \
+		-DWITH_QT=OFF \
+		-DWITH_PYTHON=OFF \
+		-DWITH_CERES=OFF \
+		-DWITH_G2O=OFF \
+		-DWITH_GTSAM=OFF \
+		-DWITH_MRPT=OFF \
+		-DWITH_VERTIGO=OFF \
+		-DWITH_CVSBA=OFF \
+		-DWITH_POINTMATCHER=OFF \
+		-DWITH_CCCORELIB=OFF \
+		-DWITH_OPEN3D=OFF \
+		-DWITH_LOAM=OFF \
+		-DWITH_FLOAM=OFF \
+		-DWITH_LIOSAM=OFF \
+		-DWITH_FLYCAPTURE2=OFF \
+		-DWITH_ZED=OFF \
+		-DWITH_ZEDOC=OFF \
+		-DWITH_REALSENSE=OFF
+}
+
+if [[ ! -f "$BUILD_DIR/CMakeCache.txt" ]]; then
+	echo "Configuring $BUILD_DIR (export headers for Doxygen)..."
+	configure_docs_build
+elif ! grep -q '^BUILD_TESTING:BOOL=OFF' "$BUILD_DIR/CMakeCache.txt" 2>/dev/null; then
+	echo "Reconfiguring $BUILD_DIR for documentation..."
+	configure_docs_build
+fi
+
+export_header="$BUILD_DIR/corelib/src/include/rtabmap/core/rtabmap_core_export.h"
+if [[ ! -f "$export_header" ]]; then
+	echo "Error: missing $export_header (CMake configure did not generate export header)" >&2
+	exit 1
+fi
+
+default_build_dir="$ROOT/build-docs"
+if [[ "$BUILD_DIR" == "$default_build_dir" ]]; then
+	echo "Running Doxygen..."
+	doxygen "$ROOT/Doxyfile"
+else
+	printf 'INPUT = corelib/include utilite/include %s/corelib/src/include\n' "$BUILD_DIR" \
+		>"$DOXY_INPUT_OVERRIDE"
+	echo "Running Doxygen (INPUT override: $DOXY_INPUT_OVERRIDE)..."
+	doxygen "$ROOT/Doxyfile" "$DOXY_INPUT_OVERRIDE"
+fi
+
+if [[ ! -f "$HTML_DIR/index.html" ]]; then
+	echo "Error: expected $HTML_DIR/index.html after Doxygen run" >&2
+	exit 1
+fi
+
+echo ""
+echo "Done: $HTML_DIR/index.html"

rosdoc-report.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Generate ROS Sphinx documentation at docs_output/rtabmap/index.html
+# Run from anywhere; requires a sourced ROS 2 install (see /opt/ros/<distro>).
+# Override: ROS_DISTRO=humble ROSDOC_OUTPUT_DIR=/path ./rosdoc-report.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROS_DISTRO="${ROS_DISTRO:-jazzy}"
+PACKAGE_NAME="${ROSDOC_PACKAGE_NAME:-rtabmap}"
+OUTPUT_DIR="${ROSDOC_OUTPUT_DIR:-$ROOT/docs_output/$PACKAGE_NAME}"
+DOC_BUILD_DIR="${ROSDOC_BUILD_DIR:-$ROOT/docs_build}"
+
+need_cmd() {
+	command -v "$1" >/dev/null 2>&1 || {
+		echo "Error: required command not found: $1" >&2
+		exit 1
+	}
+}
+
+ros_setup="/opt/ros/${ROS_DISTRO}/setup.bash"
+if [[ ! -f "$ros_setup" ]]; then
+	echo "Error: ROS setup not found: $ros_setup" >&2
+	echo "Install ROS 2 ($ROS_DISTRO) or set ROS_DISTRO to an installed distro." >&2
+	exit 1
+fi
+
+need_cmd rosdoc2
+need_cmd doxygen
+
+# Do not source a colcon workspace (rosdoc2 known issue #66).
+# shellcheck source=/dev/null
+source "$ros_setup"
+
+echo "Building ROS documentation with rosdoc2 (ROS $ROS_DISTRO)..."
+rosdoc2 build \
+	--package-path "$ROOT" \
+	--output-directory "$ROOT/docs_output" \
+	--doc-build-directory "$DOC_BUILD_DIR"
+
+if [[ ! -f "$OUTPUT_DIR/index.html" ]]; then
+	echo "Error: expected $OUTPUT_DIR/index.html after rosdoc2 build" >&2
+	exit 1
+fi
+
+echo ""
+echo "Done: $OUTPUT_DIR/index.html"