bazel-contrib / bazel-contrib/rules_python

sphinxdocs: implement content-based change detection plugin

オープン
#2,879 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
sphinxdocs type: feature request
主要言語
Starlark
スター
688
フォーク
721
平均マージ
15時間 7分
マージ済み PR(30日)
76

説明

Sphinx has change detection to facilitate incremental rebuilding, but it's timestamp based. Bazel doesn't reliably preserve timestamps, nor are timestamps highly reliable, so this functionality isn't usable. This means sphinx has to rebuild everything, every time, which can get quite slow. Pigweed, for example, takes many minutes. Even in rules_python, it takes just under a minute (long enough where I think, "its just building docs, why is this taking so long?")

To fix this, I think we can implement a plugin that uses the `env-get-outdated` event; see this comment: https://github.com/sphinx-doc/sphinx/issues/11556#issuecomment-1667507177

api docs: https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html#event-env-get-outdated

All it has to do is calculate a hash of the file and compare it to a previous hash.

Looking through those API docs, I wonder if some of those other events would be of interest, especially for a persistent worker.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

Start with Sphinx's env-get-outdated event documentation and the linked Sphinx issue comment. Investigate how a plugin can calculate and persist file hashes for comparison during incremental builds, and determine whether the other events or persistent-worker behavior matter. Done means unchanged files are skipped while changed files trigger rebuilding.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
python
領域
build-system, documentation
issue の種類
機能追加
難易度
4/5
見積もり時間
3〜5日
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

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

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