rtabmap_python tests and doc (#1455)

.github/workflows/coverage.yml

@@ -60,7 +60,7 @@ jobs:
       # tested package depends on them (--packages-up-to), just not measured.
       - uses: ros-tooling/[email protected]
         with:
-          package-name: rtabmap_conversions rtabmap_util rtabmap_sync
+          package-name: rtabmap_conversions rtabmap_util rtabmap_sync rtabmap_python
           target-ros2-distro: humble
           # RTAB-Map is installed in the image, not as an apt package, so rosdep
           # cannot resolve the key and must not try.
@@ -75,6 +75,9 @@ jobs:
             {
               "build": {
                 "mixin": ["coverage-gcc"]
+              },
+              "test": {
+                "pytest-with-coverage": true
               }
             }
           # Pinned so a change in the mixin repository cannot break this job.
@@ -115,6 +118,8 @@ jobs:
           # `source` does not exist. GitHub picks sh whenever it cannot find
           # bash in the image's PATH, and says so in the log ("shell: sh -e").
           . /opt/ros/humble/setup.sh
+          # C++ packages only -- rtabmap_python emits no .gcno for lcov to read,
+          # and is measured by the coveragepy step below instead.
           PKGS="rtabmap_conversions rtabmap_util rtabmap_sync"
           # Baseline from the .gcno files. Without it a source file that no test
           # ever loaded is missing from the report altogether rather than
@@ -129,10 +134,34 @@ jobs:
               '*CompilerId*' '*/CMakeFiles/*' || true
           test -s lcov/total_coverage.info
 
-      # Fails the job if the step above produced nothing -- the failure mode
-      # this workflow has hit twice already is a green run that measured zero.
-      - name: Coverage summary
-        run: lcov --summary ros_ws/lcov/total_coverage.info
+      # Python coverage is a separate mechanism: the coverage-gcc mixin only adds
+      # --coverage to the compiler, which does nothing for an ament_python package.
+      # colcon test --pytest-with-coverage (set above) writes a Cobertura report into
+      # the package's own build directory instead.
+      #
+      # Its paths are relative to the package rather than the repository, so
+      # cv_compression.py arrives as "rtabmap_python/cv_compression.py" -- one level
+      # short of where it really lives. Rewrite them here rather than leave Codecov to
+      # guess, which it does by suffix and can get wrong.
+      - name: Python coverage report
+        working-directory: ros_ws
+        run: |
+          python3 - <<'EOF'
+          import pathlib
+          import xml.etree.ElementTree as ET
+          p = pathlib.Path('build/rtabmap_python/coverage.xml')
+          if not p.is_file():
+              print('::warning::no python coverage produced for rtabmap_python')
+              raise SystemExit(0)
+          tree = ET.parse(p)
+          root = tree.getroot()
+          for source in root.iter('source'):
+              source.text = '.'
+          for cls in root.iter('class'):
+              cls.set('filename', 'rtabmap_python/' + cls.get('filename'))
+          tree.write(p, xml_declaration=True, encoding='utf-8')
+          print('rewrote', p, 'to repository-relative paths')
+          EOF
 
       # colcon lcov-result runs genhtml itself, into the same lcov/ directory.
       - name: Upload HTML coverage artifact
@@ -146,7 +175,7 @@ jobs:
         if: ${{ env.CODECOV_TOKEN != '' }}
         uses: codecov/codecov-action@v5
         with:
-          files: ros_ws/lcov/total_coverage.info
+          files: ros_ws/lcov/total_coverage.info,ros_ws/build/rtabmap_python/coverage.xml
           # Upload ONLY the aggregated lcov file. By default the CLI also walks
           # the tree and runs gcov over every .gcno it finds, which re-adds the
           # test sources the --filter above just dropped.