Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Debug sphinxdocs build fails when target is in root dir

Aperta Adatta ai principianti
  • Qualcosa non va?
#4,201 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
88/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python, shell
Ambito
build-system, documentation

Direzione di ricerca

Ispeziona sphinxdocs/private/sphinx_run_template.sh e _sphinx_run_impl in sphinxdocs/private/sphinx.bzl, quindi riproduci il comportamento con il checkout documentato e bazelisk run :code.run. Il lavoro è completato quando una destinazione binaria sphinx nel pacchetto root viene eseguita correttamente tramite il debug runner generato, senza l’errore env: ‘build’.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

🐞 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

Lingua principale
Starlark
Stelle
688
Fork
723
Merge medio
1g 13h
PR unite (30g)
43

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di bazel-contrib/rules_python

Tutte le issue di bazel-contrib/rules_python

Issue simili

Altre issue su Build System

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.