Hacktoberfest 2026：維護者為十月標記出來的 issue，仍然開放、適合新手。 瀏覽 Hacktoberfest issue

Debug sphinxdocs build fails when target is in root dir

已關閉 適合新手
  • 哪裡不對？
#4,201 3 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

還沒有人認領這個 Issue。

評估

難度
2/5
預估耗時
1-3 小時
新手友好度
88/100
Issue 類型
缺陷
描述清晰度
描述清楚
活躍度
活躍
技術堆疊
python, shell
領域
build-system, documentation

研究方向

檢查 sphinxdocs/private/sphinx_run_template.sh 和 sphinxdocs/private/sphinx.bzl 中的 _sphinx_run_impl，然後使用文件記載的 checkout 和 bazelisk run :code.run 重現。完成標準是：root package 中的 sphinx 二進位目標能夠透過產生的 debug runner 成功執行，且不出現 env: ‘build’ 錯誤。

由索引模型根據 Issue 內容生成。

描述

🐞 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

主要語言
Starlark
星號
688
分支
728
平均合併
22 小時 42 分鐘
30 天內合併 PR
111

環境準備

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

bazel-contrib/rules_python 的其他 Issue

查看 bazel-contrib/rules_python 的全部 Issue

相似的 Issue

更多 Build System Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。