Generate .pyi's using pybind11-stubgen

Add pybind11-stubgen as a new external. Add a rule to generate `.pyi`s
for `pydrake` using the same and a small helper script.

For now, this must be manually invoked, and some functions are being
skipped (see RobotLocomotion#17520). However, this will give us the ability to manually
test the generated `.pyi` files. Adding logic to install them and/or
otherwise bundle them can come later.

bindings/pydrake/BUILD.bazel

@@ -680,6 +680,22 @@ generate_pybind_coverage(
     xml_docstrings = ":documentation_pybind.xml",
 )
 
+drake_py_binary(
+    name = "stubgen",
+    srcs = ["stubgen.py"],
+    args = [
+        "--no-setup-py",
+        # TODO(mwoehlke-kitware): Remove when #17520 is fixed.
+        "--ignore-invalid",
+        "all",
+    ],
+    visibility = ["//bindings:__pkg__"],
+    deps = [
+        ":all_py",
+        "@pybind11_stubgen_internal//:pybind11_stubgen",
+    ],
+)
+
 add_lint_tests_pydrake(
     python_lint_extra_srcs = [
         ":test/all_install_test.py",

bindings/pydrake/stubgen.py

@@ -0,0 +1,24 @@
+"""Command-line tool to generate Drake's Python type-completion."""
+
+import sys
+import pybind11_stubgen
+
+import pydrake.all
+
+
+def _modules_to_scan():
+    names = ["pydrake"]
+    for name in sys.modules.keys():
+        if "._" in name:
+            # Private module.
+            continue
+        if name.startswith("pydrake."):
+            names.append(name)
+    return names
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    modules = _modules_to_scan()
+
+    pybind11_stubgen.main(args + modules)

tools/workspace/default.bzl

@@ -72,6 +72,7 @@ load("@drake//tools/workspace/petsc:repository.bzl", "petsc_repository")
 load("@drake//tools/workspace/picosat:repository.bzl", "picosat_repository")
 load("@drake//tools/workspace/picosha2:repository.bzl", "picosha2_repository")
 load("@drake//tools/workspace/pybind11:repository.bzl", "pybind11_repository")
+load("@drake//tools/workspace/pybind11_stubgen_internal:repository.bzl", "pybind11_stubgen_internal_repository")  # noqa
 load("@drake//tools/workspace/pycodestyle:repository.bzl", "pycodestyle_repository")  # noqa
 load("@drake//tools/workspace/pygame_py:repository.bzl", "pygame_py_repository")  # noqa
 load("@drake//tools/workspace/python:repository.bzl", "python_repository")
@@ -290,6 +291,8 @@ def add_default_repositories(excludes = [], mirrors = DEFAULT_MIRRORS):
         picosha2_repository(name = "picosha2", mirrors = mirrors)
     if "pybind11" not in excludes:
         pybind11_repository(name = "pybind11", mirrors = mirrors)
+    if "pybind11_stubgen_internal" not in excludes:
+        pybind11_stubgen_internal_repository(name = "pybind11_stubgen_internal", mirrors = mirrors)  # noqa
     if "pycodestyle" not in excludes:
         pycodestyle_repository(name = "pycodestyle", mirrors = mirrors)
     if "pygame_py" not in excludes:

tools/workspace/pybind11_stubgen_internal/BUILD.bazel

@@ -0,0 +1,8 @@
+# -*- python -*-
+
+# This file exists to make our directory into a Bazel package, so that our
+# neighboring *.bzl file can be loaded elsewhere.
+
+load("//tools/lint:lint.bzl", "add_lint_tests")
+
+add_lint_tests()

tools/workspace/pybind11_stubgen_internal/package.BUILD.bazel

@@ -0,0 +1,11 @@
+# -*- python -*-
+
+load("@drake//tools/skylark:py.bzl", "py_binary", "py_library")
+
+licenses(["notice"])  # BSD-3-Clause
+
+py_library(
+    name = "pybind11_stubgen",
+    srcs = ["pybind11_stubgen/__init__.py"],
+    visibility = ["//visibility:public"],
+)

tools/workspace/pybind11_stubgen_internal/repository.bzl

@@ -0,0 +1,15 @@
+# -*- python -*-
+
+load("@drake//tools/workspace:github.bzl", "github_archive")
+
+def pybind11_stubgen_internal_repository(
+        name,
+        mirrors = None):
+    github_archive(
+        name = name,
+        repository = "sizmailov/pybind11-stubgen",
+        commit = "2536dbc3cad276c9edea86a3af61de9a57ab644d",
+        sha256 = "e7350051a4179516cc740745d69a847eecf83dad902e6b23b18cac43dd1c9e9e",  # noqa
+        build_file = "@drake//tools/workspace/pybind11_stubgen_internal:package.BUILD.bazel",  # noqa
+        mirrors = mirrors,
+    )