Documentation Site

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ "master", "dev" ]
+    branches: [ "master" ]
   pull_request:
-    branches: [ "master", "dev" ]
+    branches: [ "master" ]
 
 jobs:
   # check python formatting
@@ -27,6 +27,20 @@ jobs:
       with:
         clang-format-version: '20'
 
+  # if it was a push to master, update latest
+  docs:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' }}
+    steps:
+      - uses: actions/checkout@v4
+        name: Checkout
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install the project
+        run: uv sync --dev --verbose
+      - name: Deploy docs
+        run: mike deploy -p -u latest
+
   # run tests on both mac and ubuntu, across all python versions
   test:
     runs-on: ${{ matrix.os }}

.github/workflows/release.yml

@@ -9,6 +9,8 @@ on:
 jobs:
   build_wheels:
     runs-on: ${{ matrix.os }}
+    env:
+      VCPKG_DEFAULT_BINARY_CACHE: "${{ github.workspace }}/.vcpkg_cache"
     strategy:
       matrix:
         os: [ubuntu-latest, macos-13, macos-14]
@@ -17,12 +19,14 @@ jobs:
         name: Checkout
 
       # Let vcpkg store caches in github actions
-      - name: Export GitHub Actions cache environment variables
-        uses: actions/github-script@v7
+      - name: Restore vcpkg cache
+        id: cache
+        uses: actions/cache/restore@v4
         with:
-          script: |
-            core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
-            core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+          path: "${{ env.VCPKG_DEFAULT_BINARY_CACHE }}"
+          key: vcpkg-${{ matrix.os }}
+      - name: Ensure vcpkg cache directory exists
+        run: mkdir -p "${{ env.VCPKG_DEFAULT_BINARY_CACHE }}"
 
       # Do all the building
       - run: ./cpp/setup_pipelines.sh
@@ -31,12 +35,24 @@ jobs:
         name: Build wheel
         env:
           # for vcpkg caches
-          CIBW_ENVIRONMENT: >
-            VCPKG_BINARY_SOURCES="clear;x-gha,readwrite" 
-            ACTIONS_CACHE_URL="$ACTIONS_CACHE_URL" 
-            ACTIONS_RUNTIME_TOKEN="$ACTIONS_RUNTIME_TOKEN"
-            MACOSX_DEPLOYMENT_TARGET="11"
-          CIBW_ENVIRONMENT_PASS_LINUX: VCPKG_BINARY_SOURCES ACTIONS_CACHE_URL ACTIONS_RUNTIME_TOKEN
+          CIBW_ENVIRONMENT_LINUX : VCPKG_DEFAULT_BINARY_CACHE="/host${{ env.VCPKG_DEFAULT_BINARY_CACHE }}"
+
+      # Delete the old cache on hit to emulate a cache update. See
+      # https://github.com/actions/cache/issues/342.
+      - name: Delete old cache
+        env:
+          GH_TOKEN: ${{ github.token }}
+        if: steps.cache.outputs.cache-hit 
+        # Using `--repo` makes it so that this step doesn't require checking out the repo first.
+        run: gh cache delete --repo ${{ github.repository }} ${{ steps.cache.outputs.cache-primary-key }}
+
+      # cache vcpkg
+      - name: Save vcpkg cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: "${{ env.VCPKG_DEFAULT_BINARY_CACHE }}"
+          key: vcpkg-${{ matrix.os }}
 
       # upload to use in other jobs
       - uses: actions/upload-artifact@v4
@@ -80,4 +96,18 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           generate_release_notes: true
-          files: dist/*
+          files: dist/*
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        name: Checkout
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install the project
+        run: uv sync --dev --verbose
+      - name: Get version
+        run: echo "EVALIO_VERSION=$(python -c 'import evalio; print(evalio.__version__)')" >> $GITHUB_ENV
+      - name: Deploy docs
+        run: mike deploy -p -u ${{ env.EVALIO_VERSION }} stable

.gitignore

@@ -7,10 +7,12 @@ wheelhouse
 .vcpkg_installed
 .vcpkg
 .vcpkg_cache
+site
 
 # other caches
 .mypy_cache
 .ruff_cache
+.pytest_cache
 .vscode
 .venv
 __pycache__

cpp/bindings/pipeline.h

@@ -50,20 +50,35 @@ class PyPipeline : public evalio::Pipeline {
 
 inline void makeBasePipeline(nb::module_ &m) {
   nb::class_<evalio::Pipeline, PyPipeline>(m, "Pipeline")
-      .def(nb::init<>())
-      .def_static("name", &evalio::Pipeline::name)
-      .def_static("default_params", &evalio::Pipeline::default_params)
-      .def_static("url", &evalio::Pipeline::url)
-      .def_static("version", &evalio::Pipeline::version)
-      .def("pose", &evalio::Pipeline::pose)
-      .def("map", &evalio::Pipeline::map)
-      .def("initialize", &evalio::Pipeline::initialize)
-      .def("add_imu", &evalio::Pipeline::add_imu, "mm"_a)
-      .def("add_lidar", &evalio::Pipeline::add_lidar, "mm"_a)
-      .def("set_params", &evalio::Pipeline::set_params, "params"_a)
-      .def("set_imu_params", &evalio::Pipeline::set_imu_params, "params"_a)
-      .def("set_lidar_params", &evalio::Pipeline::set_lidar_params, "params"_a)
-      .def("set_imu_T_lidar", &evalio::Pipeline::set_imu_T_lidar, "T"_a);
+      .def(nb::init<>(), "Construct a new pipeline.")
+      .def_static("name", &evalio::Pipeline::name, "Name of the pipeline.")
+      .def_static("default_params", &evalio::Pipeline::default_params,
+                  "Default parameters for the pipeline.")
+      .def_static("url", &evalio::Pipeline::url,
+                  "URL for more information about the pipeline.")
+      .def_static("version", &evalio::Pipeline::version,
+                  "Version of the pipeline.")
+      .def("pose", &evalio::Pipeline::pose, "Most recent pose estimate.")
+      .def("map", &evalio::Pipeline::map, "Map of the environment.")
+      .def("initialize", &evalio::Pipeline::initialize,
+           "Initialize the pipeline. Must be called after constructing the "
+           "object and before setting parameters.")
+      .def("add_imu", &evalio::Pipeline::add_imu, "mm"_a,
+           "Register an IMU measurement.")
+      .def("add_lidar", &evalio::Pipeline::add_lidar, "mm"_a,
+           "Register a LiDAR measurement.")
+      .def("set_params", &evalio::Pipeline::set_params, "params"_a,
+           "Set parameters for the pipeline. This will override any default "
+           "parameters.")
+      .def("set_imu_params", &evalio::Pipeline::set_imu_params, "params"_a,
+           "Set IMU parameters for the pipeline.")
+      .def("set_lidar_params", &evalio::Pipeline::set_lidar_params, "params"_a,
+           "Set LiDAR parameters for the pipeline.")
+      .def("set_imu_T_lidar", &evalio::Pipeline::set_imu_T_lidar, "T"_a,
+           "Set the transformation from IMU to LiDAR frame.")
+      .doc() = "Base class for all pipelines. This class defines the interface "
+               "for interacting with pipelines, and is intended to be "
+               "subclassed by specific implementations.";
 }
 
 } // namespace evalio

cpp/bindings/pipelines/bindings.h

@@ -24,8 +24,11 @@ inline void makePipelines(nb::module_ &m) {
       .def_static("name", &KissICP::name)
       .def_static("default_params", &KissICP::default_params)
       .def_static("url", &KissICP::url)
-      .def_static("version", &KissICP::version);
-
+      .def_static("version", &KissICP::version)
+      .doc() =
+      "KissICP LiDAR-only pipeline for point cloud registration. KissICP is "
+      "designed to be simple and easy to use, while still providing good "
+      "performance with minimal parameter tuning required across datasets.";
 #endif
 
 #ifdef EVALIO_LIO_SAM
@@ -34,7 +37,11 @@ inline void makePipelines(nb::module_ &m) {
       .def_static("name", &LioSam::name)
       .def_static("default_params", &LioSam::default_params)
       .def_static("url", &LioSam::url)
-      .def_static("version", &LioSam::version);
+      .def_static("version", &LioSam::version)
+      .doc() =
+      "Lidar-Inertial Smoothing and Mapping (LioSAM) pipeline. LioSAM is an "
+      "extension of LOAM (=> uses planar and edge features) that additionally "
+      "utilizes an IMU for initializing ICP steps and for dewarping points";
 #endif
 }
 } // namespace evalio