Fix Python docs build errors and warnings

docs/source/conf.py

@@ -429,7 +429,31 @@ def on_finish(_app, exception):
 }
 
 
+def drop_pybind11_bases():
+    """Stop autoclasstoc from listing pybind11's internal base classes.
+
+    Every pybind11 class inherits from `pybind11_builtins.pybind11_object`.
+    autoclasstoc walks the MRO and hands each base to autosummary, which can't
+    import it by name and warns once per class. Instead of suppressing the
+    warnings, we skip those bases since they contain nothing worth documenting.
+    """
+    from autoclasstoc import utils
+
+    find_inherited_attrs = utils.find_inherited_attrs
+
+    def find_without_pybind11_bases(cls):
+        return {
+            base: attrs
+            for base, attrs in find_inherited_attrs(cls).items()
+            if base.__module__ != "pybind11_builtins"
+        }
+
+    utils.find_inherited_attrs = find_without_pybind11_bases
+
+
 def setup(app):
+    drop_pybind11_bases()
+
     if SHOW_PROGRESS:
         connect_progress(app)
 

docs/source/tutorials/advanced_friction.rst

@@ -284,7 +284,7 @@ to each tangential collision after building the collisions:
                 collision_mesh, rest_positions, lagged_displacements, velocities)
 
 Lagged effective μ (direction-dependent coefficients)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When ``mu_s_aniso`` / ``mu_k_aniso`` are nonzero, the toolkit **lags** the
 matchstick effective coefficients for the current nonlinear step (stored in

python/src/bindings.cpp

@@ -43,6 +43,13 @@ PYBIND11_MODULE(ipctk, m)
     define_cuda_is_available(cuda);
     define_cuda_lbvh(cuda);
 
+    // We define the collision mesh and ESP parameters early because many
+    // signatures below take them. Otherwise, pybind11 falls back to the C++
+    // names (e.g., ipc::CollisionMesh) in the generated Python signatures,
+    // which the docs can't parse.
+    define_collision_mesh(m);
+    define_esp_parameters(m);
+
     // candidates
     define_candidates(m);
     define_collision_stencil(m);
@@ -137,7 +144,6 @@ PYBIND11_MODULE(ipctk, m)
     define_world_bbox_diagonal_length(m);
 
     // root
-    define_collision_mesh(m);
     define_ipc(m);
 
     // Deprecated names from before the smooth_contact -> gcp rename. We resolve

python/src/ipc.cpp

@@ -32,7 +32,9 @@ void define_ipc(py::module_& m)
         )ipc_Qu8mg5v7",
         "mesh"_a, "vertices_t0"_a, "vertices_t1"_a, "min_distance"_a = 0.0,
         "broad_phase"_a = nullptr,
-        "narrow_phase_ccd"_a = DEFAULT_NARROW_PHASE_CCD);
+        py::arg_v(
+            "narrow_phase_ccd", DEFAULT_NARROW_PHASE_CCD,
+            "TightInclusionCCD()"));
 
     m.def(
         "compute_collision_free_stepsize", &compute_collision_free_stepsize,
@@ -58,7 +60,9 @@ void define_ipc(py::module_& m)
         )ipc_Qu8mg5v7",
         "mesh"_a, "vertices_t0"_a, "vertices_t1"_a, "min_distance"_a = 0.0,
         "broad_phase"_a = nullptr,
-        "narrow_phase_ccd"_a = DEFAULT_NARROW_PHASE_CCD);
+        py::arg_v(
+            "narrow_phase_ccd", DEFAULT_NARROW_PHASE_CCD,
+            "TightInclusionCCD()"));
 
     m.def(
         "has_intersections", &has_intersections,

python/src/potentials/barrier_potential.cpp

@@ -160,7 +160,7 @@ void define_smooth_potential(py::module_& m)
                 vertices: Vertices of the collision mesh.
 
             Returns:
-                The gradient of all barrier potentials (not scaled by the barrier stiffness). This will have a size of |vertices|.
+                The gradient of all barrier potentials (not scaled by the barrier stiffness). This will have a size of \|vertices\|.
             )ipc_Qu8mg5v7",
             "collisions"_a, "mesh"_a, "vertices"_a)
         .def(
@@ -179,7 +179,7 @@ void define_smooth_potential(py::module_& m)
                 project_hessian_to_psd: Make sure the hessian is positive semi-definite.
 
             Returns:
-                The hessian of all barrier potentials (not scaled by the barrier stiffness). This will have a size of |vertices|x|vertices|.
+                The hessian of all barrier potentials (not scaled by the barrier stiffness). This will have a size of \|vertices\|x\|vertices\|.
             )ipc_Qu8mg5v7",
             "collisions"_a, "mesh"_a, "vertices"_a,
             "project_hessian_to_psd"_a = PSDProjectionMethod::NONE)
@@ -234,7 +234,7 @@ void define_smooth_potential(py::module_& m)
             "project_hessian_to_psd"_a = PSDProjectionMethod::NONE);
 }
 
-void define_esp_potential(py::module& m)
+void define_esp_parameters(py::module& m)
 {
     py::class_<ESPParameters> esp_parameters(m, "ESPParameters");
 
@@ -270,14 +270,18 @@ void define_esp_potential(py::module& m)
             )ipc_Qu8mg5v7",
             py::arg("dhat"), py::arg("dbar_factor") = 0.2,
             py::arg("quad_order") = 1, py::arg("area_weights") = true,
-            py::arg("integration_type") =
-                ESPParameters::IntegrationType::NORMAL)
+            py::arg_v(
+                "integration_type", ESPParameters::IntegrationType::NORMAL,
+                "IntegrationType.NORMAL"))
         .def_readonly("dhat", &ESPParameters::dhat)
         .def_readonly("dbar", &ESPParameters::dbar)
         .def_readonly("quad_order", &ESPParameters::quad_order)
         .def_readonly("area_weights", &ESPParameters::area_weights)
         .def_readonly("integration_type", &ESPParameters::integration_type);
+}
 
+void define_esp_potential(py::module& m)
+{
     py::class_<ESPPotential>(m, "ESPPotential")
         .def(
             py::init<const ESPParameters&, const bool>(),
@@ -322,7 +326,7 @@ void define_esp_potential(py::module& m)
                 vertices: Vertices of the collision mesh.
 
             Returns:
-                The gradient of all barrier potentials (not scaled by the barrier stiffness). This will have a size of |vertices|.
+                The gradient of all barrier potentials (not scaled by the barrier stiffness). This will have a size of \|vertices\|.
             )ipc_Qu8mg5v7",
             py::arg("collisions"), py::arg("mesh"), py::arg("vertices"))
         .def(
@@ -341,8 +345,10 @@ void define_esp_potential(py::module& m)
                 project_hessian_to_psd: Make sure the hessian is positive semi-definite. With normalized weights and edge-edge terms, each face's block is projected as a whole.
 
             Returns:
-                The hessian of all barrier potentials (not scaled by the barrier stiffness). This will have a size of |vertices|x|vertices|.
+                The hessian of all barrier potentials (not scaled by the barrier stiffness). This will have a size of \|vertices\|x\|vertices\|.
             )ipc_Qu8mg5v7",
             py::arg("collisions"), py::arg("mesh"), py::arg("vertices"),
-            py::arg("project_hessian_to_psd") = PSDProjectionMethod::NONE);
+            py::arg_v(
+                "project_hessian_to_psd", PSDProjectionMethod::NONE,
+                "PSDProjectionMethod.NONE"));
 }

python/src/potentials/bindings.hpp

@@ -4,6 +4,7 @@
 
 void define_barrier_potential(py::module_& m);
 void define_smooth_potential(py::module_& m);
+void define_esp_parameters(py::module_& m);
 void define_esp_potential(py::module_& m);
 void define_friction_potential(py::module_& m);
 void define_normal_adhesion_potential(py::module_& m);

python/src/utils/eigen_ext.cpp

@@ -51,5 +51,7 @@ void define_eigen_ext(py::module_& m)
         Returns:
             Projected matrix
         )ipc_Qu8mg5v7",
-        "A"_a, "method"_a = PSDProjectionMethod::CLAMP);
+        "A"_a,
+        py::arg_v(
+            "method", PSDProjectionMethod::CLAMP, "PSDProjectionMethod.CLAMP"));
 }