docs: autobuild loops in apps
Metadata
Current evaluation
Sphinx docs autobuild loop was fixed by merged PR #523 (commit 25d7d15), updating Starter Pack documentation variables.
Resolution: closed resolved
Reason: The maintainer explicitly recorded the issue as fixed in #523. PR #523 was merged as commit 25d7d15 and updated the Starter Pack variables associated with the rebuild loop.
Evaluated by: mr-cal-bot
No scores available.
Issue body
## Situation
In our apps, running `make docs-auto` loops after making any change to a file. This is a legacy problem; at build time, the docs dynamically generate `reference/commands` and symbolically links the docs of Craft Parts and Craft Application into the tree. Sphinx detects these as new files, and rebuilds, resulting in an infinite loop.
## Early explorations
Adding this to the start of `common.mk` should fix the problem:
```
export SPHINXOPTS ?= -c . -d .sphinx/.doctrees -j auto --ignore "common/*" --ignore "reference/commands/*"
```
But Sphinx still detects the files symlinked from the libraries:
```
Detected changes (/dev/snapcraft/.venv/lib/python3.12/site-packages/craft_parts_docs/craft-parts, /dev/snapcraft/.venv/lib/python3.12/site-packages/craft_application_docs/craft-application...
```
Does Sphinx have trouble with symbolic links?
## Request
Fix the build.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Sphinx docs autobuild loop was fixed by merged PR #523 (commit 25d7d15), updating Starter Pack documentation variables. | |
| stealth/space-bunny-alpha | — | closed resolved | Fixed by merged PR #523 (commit 25d7d15), which ignores the docs virtual environment and generated command reference during autobuilds, preventing repeated rebuilds. | |
| stealth/space-bunny-alpha | — | closed resolved | Sphinx autobuild loops were fixed by merged PR #523 (commit 25d7d15), adding Starter Pack ignores for the virtual environment and generated reference/commands. | |
| stealth/space-bunny-alpha | — | closed resolved | Sphinx autobuild loops were fixed by merged PR #523, which updated Starter Pack documentation variables to ignore virtual-environment content. | |
| qwen/qwen3.6-35b-a3b | — | — | Fixed an infinite autobuild loop in make docs-auto caused by Sphinx detecting symlinked docs as changed. Updated SPHINXOPTS to ignore the virtual environment and generated command files. Resolved and merged in PR #523. | |
| qwen/qwen3.6-35b-a3b | — | — | Fixed an infinite docs autobuild loop caused by Sphinx detecting symlinks and dynamic references. Resolution added --ignore flags for the virtual environment and reference/commands directory to SPHINXOPTS. Closed and merged in PR #523. | |
| qwen/qwen3.6-35b-a3b | — | — | Fixed an infinite autobuild loop in make docs-auto by adding ignore flags for the virtual environment and dynamically generated reference files to SPHINXOPTS. Merged in PR #523. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Fixed an infinite rebuild loop in make docs-auto by adding ignore flags for the virtual environment and dynamically generated command docs to SPHINXOPTS. Resolved and merged in PR #523. |
Update history
No update history recorded yet.
Related work
-
Likely Fixed By:
starbase#523
(confidence 99%)
Merged PR #523 is explicitly cited as the fix and corresponds to commit 25d7d15.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #523 docs: update Starter Pack variables | starbase | merged | Merged PR #523 as commit 25d7d15, correcting a Starter Pack variable name missed in #499 (8c01792). The autobuild problem was deliberately deferred to a future upstream variable. | |
| #537 build(docs): update Sphinx Stack to 2.0 | starbase | merged | Merged in canonical/starbase#537 (commit fafd1fc), upgrading docs to Sphinx Stack 2.0, locking dependencies, removing Starter Pack references, and stopping autobuild loops. | |
| #261 Update Sphinx starter pack | starbase | closed | Updated the Sphinx Starter Pack to 1.3.1 via merged PR #478, including docs Makefile passthrough targets so new projects inherit current documentation improvements and tests. | |
| #5038 Docs: Interactive builds loop | snapcraft | open | Confirmed sphinx-autobuild loop remains in the docs workflow. The tox entry point was removed, but docs/Makefile still watches docs/.venv without an explicit ignore; upstream Starbase has a fix. | |
| #275 build(docs): incorporate the latest Sphinx Starter Pack | imagecraft | merged | Merged PR #275 (commit 097e5f5), refreshing the docs build with the latest canonical Sphinx Starter Pack across 23 files; author noted the failing fast-test/build checks were unrelated. |