Reference docs for removed commands persist between builds
Metadata
Current evaluation
Closed as stale; later PR #5572 (commit a281e0362) added cleanup of obsolete generated command pages in gen_cli_docs.py.
Resolution: closed stale
Reason: The issue was abandoned after only bot-generated Jira triage comments and no closing implementation. PR #5572 later added deletion of obsolete command-reference files to the documentation generator.
Evaluated by: mr-cal-bot
No scores available.
Issue body
### Bug Description
Auto-generated pages for command references aren't tracked in Git or checked by `gen_cli_docs.py`.
I suggest we have the script check the list of command pages against the list of enabled commands, and remove any that are obsolete.
### To Reproduce
1. Checkout Snapcraft 8.5.1 or earlier.
2. Build the docs.
3. Checkout the latest Snapcraft.
4. Build the docs.
The second build fails because the references for the outdated commands (disabled in #5195) are present and unindexed.
### Relevant log output
```shell
Warning, treated as error:
/home/med/dev/snapcraft/docs/reference/commands/edit-registries.rst:document isn't included in any toctree
```
### Workaround
```shell
rm -r docs/_build docs/reference/commands
```
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed stale | Closed as stale; later PR #5572 (commit a281e0362) added cleanup of obsolete generated command pages in gen_cli_docs.py. | |
| stealth/space-bunny-alpha | — | closed stale | Closed as abandoned without implementing generator cleanup. PR #5572 (a281e0362) later removed unused command references, but did not automate stale-page deletion. | |
| qwen/qwen3.6-35b-a3b | — | — | Abandoned. The gen_cli_docs.py script was not updated to clean up obsolete command references, leaving the documentation build failure unresolved. | |
| qwen/qwen3.6-35b-a3b | — | — | Closed and synced to Jira tickets CRAFT-3884 and CRAFT-3885. The issue appears abandoned or moved to Jira, with no explicit fix documented. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Closed without resolution. The documentation build fails due to untracked stale CLI reference pages. No fix was merged, leaving the generation script unmodified to clean obsolete commands. |
Update history
No update history recorded yet.
Related work
-
Caused By:
snapcraft#5195
(confidence 100%)
Disabled the registry commands whose previously generated reference pages became stale.
-
Likely Fixed By:
snapcraft#5572
(confidence 99%)
Commit a281e0362 added obsolete RST-page cleanup to tools/docs/gen_cli_docs.py.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #5572 fix(docs): remove obsolete CLI reference pages after generation | snapcraft | merged | Merged PR #5572 (commit a281e0362) added CLI docs generator cleanup, deleting obsolete command .rst files after regeneration and resolving #5200. |