pydrake has C++ class names in the documentation

[mwoehlke-kitware]

Several bindings have C++ class names in their signatures, e.g. in pydrake.geometry.AddContactMaterial.

Besides that we'd rather have the correct Python type names in the documentation, this may be an issue for IDE completion (n.b. #16987), at least if using pybind11-stubgen to generate the .pyis.

[jwnimmer-tri]

Discussed in slack thread.

The problem stems from an incorrect execution while loading our pydrake native definitions. That can happen either because we're missing py::import(...) statements to help guide the loading order, or else because there is a circular dependency between modules in which case no loading order will succeed.

In the simple case of missing imports, @mwoehlke-kitware and/or myself will probably just add the imports ourselves.

The example above of AddContactMaterial is the latter case. There's a circular dependency between geometry <=> multibody/plant. That is a C++ physical dependency layering violation, even aside from it's consequences for pydrake. For that example, the best answer is probably that the file drake/multibody/plant/coulomb_friction.h should move into either the geometry/ folder or somewhere even lower, like math/. The other possible answer is to move the stanza m.def("AddContactMaterial", ...) from geometry_py_common.cc to plant_py.cc, possibly also moving the AddContactMaterial function itself from its current header file into coulomb_friction.h.

As we find further specific instances of cycles, we'll figure out some way to loop in the feature area owners to help decide how to break the cycles.

[mwoehlke-kitware]

Also, once #17521 lands, generating the .pyis will hopefully report (as warnings) any such issues. (It will report at least some of them; whether it reliably finds all, I am less confident in asserting. 🙂)

[jwnimmer-tri]

In #18674, I have a patch that removes any C++ types from the *.pyi stub files.

What remains here is to fix the documentation so that it doesn't have C++ class names in API signatures.

Do to that, we need to define our bindings in a dependency-topological order, so that anything used as an argument or return type is already bound (and imported!) prior to defining more bindings.

[jwnimmer-tri]

The next step is #20491. After that, we can return here to work on loading / definition order.

[jwnimmer-tri]

Actually, doing #20491 without CI checking for docstring / mypy regressions is too dangerous. We need to make progress on this issue (and add regression tests) before all other pydrake refactoring.

[jwnimmer-tri]

My WIP branch is here. I'm carving out the simpler parts into a PR train. Some of the harder parts might need to wait until pydrake re-modularization happens first. The goal for now is to get a regression test onto master relatively quickly, even if that means it has an allow-list of known bugs -- at least then we won't make things too much worse.