Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

Debug sphinxdocs build fails when target is in root dir

Ouverte Adaptée aux débutants
  • Quelque chose ne va pas ?
#4,201 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
2/5
Temps estimé
1-3 heures
Accessibilité débutants
88/100
Type d'issue
Bug
Clarté
Clairement spécifiée
Activité
Active
Stack technique
python, shell
Domaine
build-system, documentation

Piste de recherche

Inspectez sphinxdocs/private/sphinx_run_template.sh et _sphinx_run_impl dans sphinxdocs/private/sphinx.bzl, puis reproduisez le comportement avec le checkout documenté et bazelisk run :code.run. C’est terminé lorsqu’une cible binaire sphinx dans le paquet racine s’exécute correctement via le runner de débogage généré, sans l’erreur env: ‘build’.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

🐞 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

Langage dominant
Starlark
Étoiles
688
Forks
724
Merge moyen
1 j 14 h
PR mergées (30 j)
59

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de bazel-contrib/rules_python

Toutes les issues de bazel-contrib/rules_python

Issues similaires

Plus d'issues Build System

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.