[setup] Obtain sphinx via PyPI instead of the system

MODULE.bazel

@@ -293,6 +293,25 @@ bazel_dep(
     repo_name = "ruff",
 )
 
+# Load developer dependencies via pip.
+
+pip_dev = use_extension(
+    "@rules_python//python/extensions:pip.bzl",
+    "pip",
+    dev_dependency = True,
+)
+
+[
+    pip_dev.parse(
+        hub_name = "drake_sphinx",
+        python_version = python_version,
+        requirements_lock = "//setup:python/sphinx/requirements.txt",
+    )
+    for python_version in PYTHON_VERSIONS
+]
+
+use_repo(pip_dev, "drake_sphinx")
+
 # Load dependencies which are "private", i.e., not available for use by
 # downstream projects. These are all "internal use only".
 

doc/pydrake/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@drake_sphinx//:requirements.bzl", sphinx_requirement = "requirement")
 load(
     "//doc:defs.bzl",
     "DEFAULT_TEST_TAGS",
@@ -19,6 +20,7 @@ drake_py_library(
     deps = [
         "//bindings/pydrake",
         "//doc/doxygen_cxx:system_doxygen",
+        sphinx_requirement("sphinx"),
     ],
 )
 
@@ -51,6 +53,8 @@ drake_py_binary(
         "//bindings/pydrake",
         "//doc:defs",
         "@stable_baselines3_internal//:stable_baselines3",
+        sphinx_requirement("sphinx"),
+        sphinx_requirement("sphinx-rtd-theme"),
     ],
     add_test_rule = True,
     test_rule_args = [

doc/pydrake/build.py

@@ -113,13 +113,6 @@ def _build(*, out_dir, temp_dir, modules):
     assert len(os.listdir(temp_dir)) == 0
     assert len(os.listdir(out_dir)) == 0
 
-    sphinx_build = "/usr/share/sphinx/scripts/python3/sphinx-build"
-    if not os.path.isfile(sphinx_build):
-        print(
-            "Please re-run 'setup/install_prereqs' with the '--developer' flag"
-        )
-        sys.exit(1)
-
     # Create a hermetic copy of our input.  This helps ensure that only files
     # listed in BUILD.bazel will render onto the website.
     symlink_input(
@@ -161,7 +154,9 @@ def _build(*, out_dir, temp_dir, modules):
     os.environ["LANG"] = "en_US.UTF-8"
     check_call(
         [
-            sphinx_build,
+            sys.executable,
+            "-m",
+            "sphinx",
             "-b",
             "html",  # HTML output.
             "-a",

setup/python/sphinx/BUILD.bazel

@@ -0,0 +1,20 @@
+load("@rules_python//python/uv:lock.bzl", "lock")
+load("//tools/lint:lint.bzl", "add_lint_tests")
+
+package(default_visibility = ["//visibility:public"])
+
+lock(
+    name = "lock",
+    srcs = ["requirements.in"],
+    out = "requirements.txt",
+    args = [
+        "--upgrade",
+        "--universal",
+        "--exclude-newer=1 week",
+        # This is our minimum supported version.
+        # When changing this, see drake/tools/workspace/python/README.md.
+        "--python-version=3.12",
+    ],
+)
+
+add_lint_tests()

setup/python/sphinx/requirements.in

@@ -0,0 +1,2 @@
+sphinx==7.2.6
+sphinx-rtd-theme==2.0.0

setup/ubuntu/packages-noble-developer.txt

@@ -29,8 +29,6 @@ python3-opencv
 python3-psutil
 python3-requests
 python3-six
-python3-sphinx
-python3-sphinx-rtd-theme
 python3-u-msgpack
 python3-uritemplate
 python3-websockets

setup/ubuntu/packages-resolute-developer.txt

@@ -27,8 +27,6 @@ python3-opencv
 python3-psutil
 python3-requests
 python3-six
-python3-sphinx
-python3-sphinx-rtd-theme
 python3-u-msgpack
 python3-uritemplate
 python3-websockets

tools/workspace/python/README.md

@@ -13,6 +13,7 @@ version on macOS), the following files need attention:
 - `drake/setup/install_prereqs` in the `"Darwin"` branch call to `python3.##`,
 - `drake/setup/python/lief/BUILD.bazel` near `--python-version`,
 - `drake/setup/python/mypy/BUILD.bazel` near `--python-version`,
+- `drake/setup/python/sphinx/BUILD.bazel` near `--python-version`,
 - `drake/setup/python/pyproject.toml` near `requires-python`,
 - `drake/tools/wheel/image/setup.py` near `python_requires` and `py_limited_api`,
 - `drake/tools/wheel/wheel_builder/common.py` near `wheel_name`,

tools/workspace/python/venv_upgrade

@@ -5,11 +5,9 @@
 # - Users can make edits to drake/setup/python/pyproject.toml, and then
 #   run this script to compile it to drake/setup/python/pdm.lock.
 #
-# - Users can make edits to drake/setup/python/mypy/requirements.in, and then
-#   run this script to compile it to drake/setup/python/mypy/requirements.txt.
-#
-# - Users can make edits to drake/setup/python/lief/requirements.in, and then
-#   run this script to compile it to drake/setup/python/lief/requirements.txt.
+# - Users can make edits to each PyPI dependency obtained via rules_python in
+#   drake/setup/python/{root}/requirements.in, and then run this script to
+#   compile it to drake/setup/python/{root}/requirements.txt.
 #
 # The --reuse option may be given to apply changes to pyproject.toml while
 # attempting to preserve existing version pins.
@@ -126,15 +124,12 @@ done
 # Check for changes to the pdm lock file.
 files_to_commit+=( "$(git diff --name-only HEAD -- "${lockfile}")" )
 
-# Upgrade the mypy lock file.
-readonly mypy_requirements="./setup/python/mypy/requirements.txt"
-bazel run //setup/python/mypy:lock.update
-files_to_commit+=( "$(git diff --name-only HEAD -- "${mypy_requirements}")" )
-
-# Upgrade the lief lock file.
-readonly lief_requirements="./setup/python/lief/requirements.txt"
-bazel run //setup/python/lief:lock.update
-files_to_commit+=( "$(git diff --name-only HEAD -- "${lief_requirements}")" )
+# Upgrade the PyPI lock files.
+for root in lief mypy sphinx; do
+    package_requirements="./setup/python/${root}/requirements.txt"
+    bazel run //setup/python/${root}:lock.update
+    files_to_commit+=( "$(git diff --name-only HEAD -- "${package_requirements}")" )
+done
 
 # If committing, do the commit.
 if [ -n "${commit}" ]; then