← Back to issue list

Docs: Interactive builds loop

View original Github issue

Metadata

Project
snapcraft
Number
#5038
Type
issue
State
open
Author
medubelko
Labels
Status: Triaged Type: Bug Type: Documentation
Created
Updated
Closed
—

Current evaluation

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.

Suggested action: keep open

Reason: The issue is triaged as a documentation bug, and the maintainer confirmed on 2025-05-05 that it still occurs; another user reported the same loop. Although tox.ini was removed, docs/Makefile still runs sphinx-autobuild with docs/.venv inside the watched tree and no visible ignore option, so the workflow was replaced rather than demonstrably fixed.

Evaluated by: mr-cal-bot

Impact: 35 Quick Win: 13 Complexity: 42 Confidence: 91 Actionability: 64

Issue body

### Bug Description As I [covered recently](https://github.com/canonical/snapcraft/blob/main/HACKING.md?plain=1#L69-L71), interactive builds run in an infinite loop. ### To Reproduce 1. Run: ```bash tox run -e autobuild-docs ``` After it first builds, no issues are detected. 2. Save a change to any RST file in `/docs`. The docs begin rebuilding in a loop. ### Environment System: Ubuntu 24.04 Environment: Snapcraft repo, no LXD/Multipass setup. ### snapcraft.yaml ```yaml - ``` ### Relevant log output ```shell [sphinx-autobuild] Detected change. Rebuilding... [sphinx-autobuild] > sphinx-build -b html /home/med/dev/snapcraft/docs /home/med/dev/snapcraft/docs/_build ``` ### Additional context @tigarmo This might be related to importing docs inside of other docs. Another TA reported similar issues a few months ago and their temporary solution was to exclude some of the content from rebuild. We found others that vouch for this being a possibility: https://github.com/sphinx-doc/sphinx/issues/11556#issuecomment-1667451983. I haven't looked into this deeply, though. If we could get `sphinx-autobuild` to specify what files it detects have changed, this would be easier to diagnose, but even with the `-v` option it merely says `Detected change`.

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha
Impact: 35
Quick Win: 13
Complexity: 42
Confidence: 91
Actionability: 64
keep 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.
qwen/qwen3.6-35b-a3b
Impact: 60
Quick Win: 34
Complexity: 30
Confidence: 85
Actionability: 80
close resolved sphinx-autobuild runs in an infinite loop when docs are rebuilt. Upstream fix in canonical/starbase#496 (PR #523) resolved the issue by updating SPHINXOPTS to ignore the virtual environment and generated command files.
qwen/qwen3.8-27b
Impact: 30
Quick Win: 18
Staleness: 55
Complexity: 40
Confidence: 72
Support Request: 10
close stale sphinx-autobuild enters infinite rebuild loop when editing RST files in /docs. Triaged bug; upstream fix (starbase#496) merged into common.mk with --ignore flags. Likely resolved but not confirmed by reporter.
qwen/qwen3.6-35b-a3b
Staleness: 25
Complexity: 65
Confidence: 90
Support Request: 10
keep open Docs: Interactive builds loop. Issue is triaged, valid, and actively discussed by maintainers. Confirmed still occurring with recent updates.
qwen3.6-35b-a3b-mtp-q6
Staleness: 45
Complexity: 40
Confidence: 90
Support Request: 10
keep open Interactive sphinx-autobuild enters an infinite rebuild loop when docs change. Triaged and confirmed still occurring; linked to upstream canonical/starbase#496.

Update history

No update history recorded yet.

Related work

  • Related To: canonical/starbase#496 (confidence 98%)

    Explicitly linked in the latest comment; it tracks the same Sphinx autobuild loop and is now closed.

  • Likely Fixed By: canonical/starbase#523 (confidence 78%)

    Merged upstream fix adds virtual-environment exclusions to Starter Pack docs, but equivalent exclusions are not visible in Snapcraft's Makefile.

Related issues

Issue Project State Summary Similarity
#496 docs: autobuild loops in apps starbase closed Sphinx docs autobuild loop was fixed by merged PR #523 (commit 25d7d15), updating Starter Pack documentation variables.
72%