From 8203c6c40f33c6b21e8492c0a5baa7e58a113440 Mon Sep 17 00:00:00 2001
From: Kayce Basques <kaycebasques@gmail.com>
Date: Wed, 14 Oct 2026 03:55:14 +0000
Subject: [PATCH] fix(sphinx): prefix sphinx binary paths with ./ in run script
 (#4201)

When the sphinx binary target is in the root package, its short_path
contains no directory separator. Executing it via `env` in the `.run`
script searches `$PATH` instead of the current directory and fails with
`No such file or directory`.

Prefix `%SPHINX_RUNFILES_PATH%` and `%SPHINX_EXEC_PATH%` with `./` in
`sphinx_run_template.sh` so `env` resolves the binary relative to the
working directory.

Fixes #4201
---
 news/4201.fixed.md                                   |  3 +++
 sphinxdocs/sphinxdocs/private/sphinx_run_template.sh |  2 +-
 sphinxdocs/tests/sphinx_docs/BUILD.bazel             |  5 ++++-
 .../tests/sphinx_docs/sphinx_docs_output_test.py     | 12 ++++++++++++
 4 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100644 news/4201.fixed.md

diff --git a/news/4201.fixed.md b/news/4201.fixed.md
new file mode 100644
index 0000000000..f686516494
--- /dev/null
+++ b/news/4201.fixed.md
@@ -0,0 +1,3 @@
+(sphinxdocs) Fixed `sphinx_docs` `.run` targets failing to locate the `sphinx`
+binary when defined in the root package
+([#4201](https://github.com/bazel-contrib/rules_python/issues/4201)).
diff --git a/sphinxdocs/sphinxdocs/private/sphinx_run_template.sh b/sphinxdocs/sphinxdocs/private/sphinx_run_template.sh
index aa83757c1b..b2371f6f8a 100644
--- a/sphinxdocs/sphinxdocs/private/sphinx_run_template.sh
+++ b/sphinxdocs/sphinxdocs/private/sphinx_run_template.sh
@@ -18,7 +18,7 @@ if [[ -z "$source_dir" ]]; then
     exit 1
 fi
 
-for path in "%SPHINX_RUNFILES_PATH%" "%SPHINX_EXEC_PATH%"; do
+for path in "./%SPHINX_RUNFILES_PATH%" "./%SPHINX_EXEC_PATH%"; do
   if [[ -e $path ]]; then
     sphinx=$path
     break
diff --git a/sphinxdocs/tests/sphinx_docs/BUILD.bazel b/sphinxdocs/tests/sphinx_docs/BUILD.bazel
index 99b84ce801..87e014fad1 100644
--- a/sphinxdocs/tests/sphinx_docs/BUILD.bazel
+++ b/sphinxdocs/tests/sphinx_docs/BUILD.bazel
@@ -89,6 +89,9 @@ build_test(
 py_test(
     name = "sphinx_docs_output_test",
     srcs = ["sphinx_docs_output_test.py"],
-    data = [":docs"],
+    data = [
+        ":docs",
+        ":docs.run",
+    ],
     deps = ["@pypi//absl_py"],
 )
diff --git a/sphinxdocs/tests/sphinx_docs/sphinx_docs_output_test.py b/sphinxdocs/tests/sphinx_docs/sphinx_docs_output_test.py
index f4e91048d3..a4a7067695 100644
--- a/sphinxdocs/tests/sphinx_docs/sphinx_docs_output_test.py
+++ b/sphinxdocs/tests/sphinx_docs/sphinx_docs_output_test.py
@@ -42,6 +42,18 @@ def test_custom_sphinx_docs_library_info_transitives(self):
         )
         self.assertTrue(os.path.exists(str(page_path)), f"Not found at {page_path}")
 
+    def test_sphinx_run_script_uses_relative_sphinx_paths(self):
+        # Verify the generated .run script prefixes the sphinx binary paths with "./"
+        # so `env` resolves the binary relative to the working directory instead of
+        # searching $PATH when the target is in the root package (where short_path
+        # has no slash). See https://github.com/bazel-contrib/rules_python/issues/4201.
+        docs_run_path = importlib.resources.files(sphinx_docs).joinpath("docs.run")
+        script_content = docs_run_path.read_text()
+        self.assertIn(
+            'for path in "./tests/sphinx_docs/sphinx-build" "./bazel-out/',
+            script_content,
+        )
+
 
 if __name__ == "__main__":
     absltest.main()