diff --git a/docs/source/conf.py b/docs/source/conf.py index a0fdd383a..bb6add463 100644 --- a/docs/source/conf.py +++ b/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) diff --git a/docs/source/tutorials/advanced_friction.rst b/docs/source/tutorials/advanced_friction.rst index 25ce09bff..b3b2471e0 100644 --- a/docs/source/tutorials/advanced_friction.rst +++ b/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 diff --git a/python/src/bindings.cpp b/python/src/bindings.cpp index 88642b749..0e56f2766 100644 --- a/python/src/bindings.cpp +++ b/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 diff --git a/python/src/ipc.cpp b/python/src/ipc.cpp index 48d3dad1d..9cb5f967e 100644 --- a/python/src/ipc.cpp +++ b/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, diff --git a/python/src/potentials/barrier_potential.cpp b/python/src/potentials/barrier_potential.cpp index a08695cf7..4fda9e05c 100644 --- a/python/src/potentials/barrier_potential.cpp +++ b/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_ 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_(m, "ESPPotential") .def( py::init(), @@ -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")); } diff --git a/python/src/potentials/bindings.hpp b/python/src/potentials/bindings.hpp index fc8162bac..1bf8c5ebd 100644 --- a/python/src/potentials/bindings.hpp +++ b/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); diff --git a/python/src/utils/eigen_ext.cpp b/python/src/utils/eigen_ext.cpp index 0f8afef12..6ca011ef3 100644 --- a/python/src/utils/eigen_ext.cpp +++ b/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")); }