Debug sphinxdocs build fails when target is in root dir

[kaycebasques]

🐞 bug report

(I let an agent generate this report. I've verified the minimal repro steps as well as the workaround.)

Affected Rule

The issue is caused by the rule: sphinx_docs / sphinx_run (@sphinxdocs//sphinxdocs:sphinx.bzl)

Is this a regression?

No.

Description

When a sphinx_docs target specifies a sphinx binary target defined in the root package of the main repository (e.g., //:build), building the docs normally (bazel build :code) succeeds, but running the generated debug runner target (bazel run :code.run) fails with env: ‘build’: No such file or directory.

Root cause:

1. In _sphinx_run_impl (sphinxdocs/private/sphinx.bzl), %SPHINX_RUNFILES_PATH% in sphinx_run_template.sh is substituted with sphinx[DefaultInfo].files_to_run.executable.short_path.
2. When the sphinx binary target is in the root package (//:build), its short_path is "build" (which contains no / directory separator).
3. At runtime, code.run executes in its runfiles directory (code.run.runfiles/_main) and resolves $sphinx:

   for path in "build" "bazel-out/k8-opt-exec/bin/build"; do
     if [[ -e $path ]]; then
       sphinx=$path
       break
     fi
   done

   Because build exists in the current working directory, [[ -e "build" ]] succeeds and sets sphinx="build".
4. Finally, code.run runs:

   exec env "${sphinx_env[@]}" -- "$sphinx" "${args[@]}" "$@" "$source_dir" "$output_dir"

   Because "build" does not contain a slash (/), env (execvp) searches $PATH instead of the current working directory and fails with env: ‘build’: No such file or directory.

Suggested fix:
In sphinxdocs/private/sphinx_run_template.sh, prefix ./ when checking/assigning relative paths (e.g., for path in "./%SPHINX_RUNFILES_PATH%" "./%SPHINX_EXEC_PATH%"; do or sphinx="./$path").

🔬 Minimal Reproduction

git clone https://github.com/kaycebasques/experiments.git
cd experiments
git checkout 8bd9278d07ee7a8da916941e967e5f20b5354f7a
cd 20260930
bazelisk build :code      # succeeds
bazelisk run :code.run    # fails

(Workaround: in 20260930/BUILD.bazel, renaming the binary target from name = "build" to name = "bin/build" or moving it into a subpackage so short_path contains a / makes bazel run :code.run succeed.)

🔥 Exception or Error

INFO: Running command line: bazel-bin/code.run
+ exec env -- build --show-traceback --builder=html --fail-on-warning _code/_sources /tmp/sphinx-out
env: ‘build’: No such file or directory

🌍 Your Environment

Operating System:

  
Linux (Debian x86_64)
  

Output of bazel version:

  
Bazelisk version: v1.28.1
Build label: 9.2.0
  

Rules_python version:

  
rules_python: 1.8.5
sphinxdocs: 2.2.0
  

Anything else relevant?

N/A

[aignas]

The suggested fix sounds good to me, if you have time to contribute a fix that would be very much appreciated.