Auto generate and deploy documentation

.github/workflows/gendoc.yml

@@ -0,0 +1,38 @@
+name: gendoc
+
+on:
+  push:
+    tags:
+      - '*'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  gendoc:
+    name: Generate documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name : Install dependencies
+        run: sudo apt-get install -y git cmake build-essential doxygen graphviz python3-dev python3-pip pybind11-dev libeigen3-dev libomp-dev python3-numpy python3-sphinx python3-sphinx-rtd-theme
+
+      - name: Install python dependencies
+        run: python -m pip install mkdocs mkdocs-material
+
+      - name: Generate documentation
+        run: cd docs && make all
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: ./site/*
+
+      - name: Deploy documentation
+        run: cd docs && make deploy

docs/Makefile

@@ -25,4 +25,4 @@ all: cpp py mkdocs
 .PHONY: deploy
 deploy:
 	@echo "Deploying documentation..."
-	cd .. && mkdocs gh-deploy
+	cd .. && mkdocs gh-deploy --force

docs/conf.py

@@ -9,6 +9,7 @@
 project = 'small_gicp'
 copyright = '2024, k.koide'
 author = 'k.koide'
+version = '0.1.1'
 
 import os
 import sys
@@ -22,6 +23,7 @@
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+autoclass_content = 'both'
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

mkdocs.yml

@@ -22,10 +22,6 @@ markdown_extensions:
     - pymdownx.inlinehilite
     - pymdownx.snippets
     - pymdownx.superfences
-    - pymdownx.emoji:
-        emoji_index: !!python/name:materialx.emoji.twemoji
-        emoji_generator: !!python/name:materialx.emoji.to_svg
-    - fontawesome_markdown
 
 copyright: Copyright © 2024 Kenji Koide
 extra:

src/python/align.cpp

@@ -99,11 +99,11 @@ void define_align(py::module& m) {
 
         Parameters
         ----------
-        target_points : NDArray[np.float64]
+        target_points : numpy.ndarray[np.float64]
             Nx3 or Nx4 matrix representing the target point cloud.
-        source_points : NDArray[np.float64]
+        source_points : numpy.ndarray[np.float64]
             Nx3 or Nx4 matrix representing the source point cloud.
-        init_T_target_source : np.ndarray[np.float64]
+        init_T_target_source : numpy.ndarray[np.float64]
             4x4 matrix representing the initial transformation from target to source.
         registration_type : str = 'GICP'
             Type of registration algorithm to use ('ICP', 'PLANE_ICP', 'GICP', 'VGICP').
@@ -117,9 +117,10 @@ void define_align(py::module& m) {
             Number of threads to use for parallel processing.
         max_iterations : int = 20
             Maximum number of iterations for the optimization algorithm.
+
         Returns
         -------
-        RegistrationResult
+        result : RegistrationResult
             Object containing the final transformation matrix and convergence status.
         )pbdoc");
 
@@ -173,7 +174,7 @@ void define_align(py::module& m) {
         Pointer to the source point cloud.
     target_tree : KdTree<PointCloud>::ConstPtr, optional
         Pointer to the KD-tree of the target for nearest neighbor search. If nullptr, a new tree is built.
-    init_T_target_source : NDArray[np.float64]
+    init_T_target_source : numpy.ndarray[np.float64]
         4x4 matrix representing the initial transformation from target to source.
     registration_type : str = 'GICP'
         Type of registration algorithm to use ('ICP', 'PLANE_ICP', 'GICP').
@@ -183,9 +184,10 @@ void define_align(py::module& m) {
         Number of threads to use for computation.
     max_iterations : int = 20
         Maximum number of iterations for the optimization algorithm.
+
     Returns
     -------
-    RegistrationResult
+    result : RegistrationResult
         Object containing the final transformation matrix and convergence status.
     )pbdoc");
 
@@ -221,7 +223,7 @@ void define_align(py::module& m) {
         Voxel map constructed from the target point cloud.
     source : PointCloud
         Source point cloud to align to the target.
-    init_T_target_source : NDArray[np.float64]
+    init_T_target_source : numpy.ndarray[np.float64]
         4x4 matrix representing the initial transformation from target to source.
     max_correspondence_distance : float = 1.0
         Maximum distance for corresponding point pairs.
@@ -232,7 +234,7 @@ void define_align(py::module& m) {
 
     Returns
     -------
-    RegistrationResult
+    result : RegistrationResult
         Object containing the final transformation matrix and convergence status.
     )pbdoc");
 }

src/python/factors.cpp

@@ -22,7 +22,18 @@ void define_factors(py::module& m) {
   // DistanceRejector
   py::class_<DistanceRejector>(m, "DistanceRejector", "Correspondence rejection based on the distance between points.")
     .def(py::init<>())
-    .def("set_max_distance", [](DistanceRejector& rejector, double dist) { rejector.max_dist_sq = dist * dist; }, py::arg("dist"), "Set the maximum distance.");
+    .def(
+      "set_max_distance",
+      [](DistanceRejector& rejector, double dist) { rejector.max_dist_sq = dist * dist; },
+      py::arg("dist"),
+      R"pbdoc(
+        Set maximum correspondence distance.
+
+        Parameters
+        ----------
+        dist : float
+            Maximum correspondence distance.
+        )pbdoc");
 
   // ICPFactor
   py::class_<ICPFactor>(m, "ICPFactor", "ICP per-point factor")
@@ -49,7 +60,35 @@ void define_factors(py::module& m) {
       py::arg("T"),
       py::arg("source_index"),
       py::arg("rejector"),
-      "Linearize the factor. Returns a tuple of success, Hessian, gradient, and error.");
+      R"pbdoc(
+        Linearize the factor.
+
+        Parameters
+        ----------
+        target : PointCloud
+            Target point cloud.
+        source : PointCloud
+            Source point cloud.
+        kdtree : KdTree
+            KdTree for the target point cloud.
+        T : numpy.ndarray
+            Transformation matrix. (4x4)
+        source_index : int
+            Index of the source point.
+        rejector : DistanceRejector
+            Correspondence rejector.
+
+        Returns
+        -------
+        success: bool
+            Success flag.
+        H : numpy.ndarray
+            Hessian matrix (6x6).
+        b : numpy.ndarray
+            Gradient vector (6,).
+        e : float
+            Error.
+        )pbdoc");
 
   // PointToPlaneICPFactor
   py::class_<PointToPlaneICPFactor>(m, "PointToPlaneICPFactor", "Point-to-plane ICP per-point factor")
@@ -76,7 +115,35 @@ void define_factors(py::module& m) {
       py::arg("T"),
       py::arg("source_index"),
       py::arg("rejector"),
-      "Linearize the factor. Returns a tuple of success, Hessian, gradient, and error.");
+      R"pbdoc(
+        Linearize the factor.
+
+        Parameters
+        ----------
+        target : PointCloud
+            Target point cloud.
+        source : PointCloud
+            Source point cloud.
+        kdtree : KdTree
+            KdTree for the target point cloud.
+        T : numpy.ndarray
+            Transformation matrix. (4x4)
+        source_index : int
+            Index of the source point.
+        rejector : DistanceRejector
+            Correspondence rejector.
+
+        Returns
+        -------
+        success: bool
+            Success flag.
+        H : numpy.ndarray
+            Hessian matrix (6x6).
+        b : numpy.ndarray
+            Gradient vector (6,).
+        e : float
+            Error.
+        )pbdoc");
 
   // GICPFactor
   py::class_<GICPFactor>(m, "GICPFactor", "Generalized ICP per-point factor")  //
@@ -103,5 +170,33 @@ void define_factors(py::module& m) {
       py::arg("T"),
       py::arg("source_index"),
       py::arg("rejector"),
-      "Linearize the factor. Returns a tuple of success, Hessian, gradient, and error.");
+      R"pbdoc(
+        Linearize the factor.
+
+        Parameters
+        ----------
+        target : PointCloud
+            Target point cloud.
+        source : PointCloud
+            Source point cloud.
+        kdtree : KdTree
+            KdTree for the target point cloud.
+        T : numpy.ndarray
+            Transformation matrix. (4x4)
+        source_index : int
+            Index of the source point.
+        rejector : DistanceRejector
+            Correspondence rejector.
+
+        Returns
+        -------
+        success: bool
+            Success flag.
+        H : numpy.ndarray
+            Hessian matrix (6x6).
+        b : numpy.ndarray
+            Gradient vector (6,).
+        e : float
+            Error.
+        )pbdoc");
 }