bazel-contrib / bazel-contrib/rules_python

sphinxdocs: implement content-based change detection plugin

未关闭
#2,879 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
sphinxdocs type: feature request
主要语言
Starlark
星标
688
派生
721
平均合并
15 小时 7 分钟
30 天内合并 PR
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 摘要。