Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Debug sphinxdocs build fails when target is in root dir

オープン 初心者向け
  • 何か問題がありますか？
#4,201 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
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 パッケージ内の sphinx バイナリターゲットが、env: ‘build’ エラーなしで生成された debug runner を介して正常に実行されれば完了です。

索引モデルが 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
フォーク
723
平均マージ
1日 15時間
マージ済み PR（30日）
40

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

bazel-contrib/rules_python のほかの issue

bazel-contrib/rules_python の issue をすべて見る

似ている issue

Build System の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。