[nanobind] Website API reference

[jwnimmer-tri]

Per #21572 we are switching to nanobind. There is a flag to choose pybind11 vs nanobind, currently defaulted to pybind11.

If we try a documentation preview bazel run //doc/pydrake:build --@drake//tools/flags:python_binder=nanobind -- --serve with nanobind, it is notably worse. Most functions are missing signatures.

This isn't urgent (since we won't switch the website to use the new docs right away), but still needs attention. Ideally we'd fix it before switching the default (in 3 months), but at worst we could force the docs build to use pybind11, and then fix it before the final pybind11 removal (in 6 months).

Possibly sphinx-autodoc-typehints would help us fix this.

[jwnimmer-tri]

See also wjakob/nanobind#1147 and sphinx-doc/sphinx#13868 for advice.

Possibly sphinx-autodoc-typehints would help us fix this.

It seems not. I installed it with apt, added it to conf.py, and added the *.pyi files as data to the rule, with no change. I didn't look carefully for any mistakes though, so maybe it's still possible with some more tweaks.

It's also possible that upgrading sphinx & etc to newer version(s) might help. I don't mind if we need to do that as part of the fix here. (You can test with a manually-installed version; if it fixes the problem, I can help automate it into Bazel.)

[tyler-yankee]

It's also possible that upgrading sphinx & etc to newer version(s) might help. I don't mind if we need to do that as part of the fix here.

FWIW it's probably orthogonal to this issue, but I would find it much more maintainable for drake to depend on sphinx via e.g. rules_python+PyPI instead of the system. I recall when we bumped the developer platform to Noble there was a lot of churn during that process in just restoring state to the website, due to the new major version of python3-sphinx shipped by Noble.

[jwnimmer-tri]

The only reason we used the OS version was because it was easier at the time we adopted Sphinx. If switching to PyPI now is easier than OS, that's fine!