Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

Debug sphinxdocs build fails when target is in root dir

Offen Anfängerfreundlich
  • Stimmt etwas nicht?
#4,201 3 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@kaycebasques arbeitet bereits daran.

Seit 14.10.2026.

  • #4261 von @kaycebasques — offen

Bewertung

Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Anfängerfreundlichkeit
88/100
Issue-Typ
Bug
Klarheit
Klar beschrieben
Aktivitätsstatus
Aktiv
Tech-Stack
python, shell
Bereich
build-system, documentation

Rechercherichtung

Untersuche sphinxdocs/private/sphinx_run_template.sh und _sphinx_run_impl in sphinxdocs/private/sphinx.bzl und reproduziere das mit dem dokumentierten Checkout und bazelisk run :code.run. Erledigt ist die Aufgabe, wenn ein sphinx-Binärziel im Root-Paket erfolgreich über den generierten Debug-Runner ausgeführt wird, ohne den Fehler env: ‘build’.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

🐞 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

Vorherrschende Sprache
Starlark
Sterne
687
Forks
726
Ø Merge
1 T. 10 Std.
Gemergte PRs (30 T.)
69

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus bazel-contrib/rules_python

Alle Issues in bazel-contrib/rules_python

Ähnliche Issues

Weitere Issues zu Build System

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.