build(docs): update Sphinx Stack to 2.0
Metadata
Current evaluation
Merged PR migrating docs tooling to Sphinx Stack 2.0: renames .sphinx to _dev, docs-starter-pack to docs-sphinx-stack, switches to sphinx_rerediraffe, adds sphinx-llm and templates.
Resolution: closed resolved
Reason: PR #1215 was merged after approval with all CI checks passing. It updates the docs toolchain to Sphinx Stack 2.0 and regenerates uv.lock.
Evaluated by: mr-cal-bot
No scores available.
Issue body
🤖 This is a preparation PR for the Starbase sync, isolating the Sphinx Stack 2.0 migration.
### Summary
- Renames the docs tooling directory from `docs/.sphinx/` to `docs/_dev/` across configuration files and scripts.
- Renames the `docs-starter-pack` dependency group to `docs-sphinx-stack` and adopts the Sphinx Stack 2.0 toolchain (`canonical-sphinx`, `sphinx-llm`, `sphinx-rerediraffe`, `sphinx-markdown-builder`, etc.).
- Migrates `docs/conf.py`'s redirect mechanism from `sphinxext.rediraffe` to `sphinx_rerediraffe` (`rediraffe_dir_only = True`), dropping `sphinxext-rediraffe`.
- Adds `sphinx-llm` (`llms.txt` generation), `linkcheck_report_timeouts_as_broken`, `docs/_templates/{header,footer}.html`, and associated Starbase docs conventions while preserving all Craft-Application-specific metadata, docs pages, and links.
- Regenerates `uv.lock` for the updated docs group.
Provenance:
- Starbase PR: [canonical/starbase#537](https://github.com/canonical/starbase/pull/537)
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| ~deepseek/deepseek-pro-latest | — | closed resolved | Merged PR migrating docs tooling to Sphinx Stack 2.0: renames .sphinx to _dev, docs-starter-pack to docs-sphinx-stack, switches to sphinx_rerediraffe, adds sphinx-llm and templates. | |
| ~deepseek/deepseek-pro-latest |
Impact:
35
Quick Win:
15
Complexity:
50
Confidence:
85
Actionability:
85
|
needs review | Migrates docs tooling to Sphinx Stack 2.0: renames .sphinx to _dev, docs-starter-pack to docs-sphinx-stack, switches rediraffe extension, adds sphinx-llm and templates; approved, CI passing. | |
| ~deepseek/deepseek-pro-latest |
Impact:
45
Quick Win:
16
Complexity:
50
Confidence:
75
Actionability:
70
|
needs review | Migrates docs tooling to Sphinx Stack 2.0: renames docs/.sphinx to docs/_dev and docs-starter-pack group to docs-sphinx-stack, switches redirects to sphinx_rerediraffe, adds sphinx-llm/templates, regenerates uv.lock. Approved with one unresolved comment; CI pending. | |
| ~deepseek/deepseek-pro-latest |
Impact:
25
Quick Win:
10
Complexity:
40
Confidence:
75
Actionability:
65
|
needs review | Migrates docs to Sphinx Stack 2.0: renames docs/.sphinx to docs/_dev, docs-starter-pack group to docs-sphinx-stack, switches to sphinx_rerediraffe, adds sphinx-llm and templates, regenerates uv.lock. Approved, CI green, 2 unresolved comments. | |
| ~deepseek/deepseek-pro-latest |
Impact:
35
Quick Win:
17
Complexity:
40
Confidence:
85
Actionability:
80
|
needs review | Migrates docs tooling to Sphinx Stack 2.0: renames docs/.sphinx to docs/_dev and docs-starter-pack group to docs-sphinx-stack, switches rediraffe to sphinx_rerediraffe, adds sphinx-llm and templates, regenerates uv.lock. CI passing, awaiting review. | |
| ~deepseek/deepseek-pro-latest |
Impact:
35
Quick Win:
17
Complexity:
40
Confidence:
82
Actionability:
80
|
needs review | Migrates docs tooling to Sphinx Stack 2.0: renames docs/.sphinx→docs/_dev, docs-starter-pack→docs-sphinx-stack, adopts canonical-sphinx/sphinx-llm/sphinx-rerediraffe, regenerates uv.lock. CI green, awaiting review. | |
| ~deepseek/deepseek-pro-latest |
Impact:
30
Quick Win:
10
Complexity:
40
Confidence:
65
Actionability:
55
|
needs review | Migrates docs tooling to Sphinx Stack 2.0: renames docs/.sphinx to docs/_dev and docs-starter-pack group to docs-sphinx-stack, switches rediraffe to sphinx_rerediraffe, adds sphinx-llm/templates, regenerates uv.lock. CI pending, no failures yet. |
Update history
| Date | Change |
|---|---|
| merged | |
| updated | |
| updated | |
| updated | |
| updated | |
| updated | |
| created |
Related work
-
Related To:
canonical/starbase#537
(confidence 90%)
Source Starbase PR from which this Sphinx Stack 2.0 migration was isolated.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #497 build(docs): update Sphinx Stack to 2.0 | craft-cli | merged | Merged PR updating documentation tooling to Sphinx Stack 2.0, migrating from .sphinx to docs/_dev, updating conf.py and Makefile, and adding new documentation files. Upstreamed from canonical/starbase#537. | |
| #275 build(docs): upgrade to Sphinx Stack 2.0 | craft-platforms | closed | Merged as commit 75dff07, upgrading the documentation configuration and dependencies to Sphinx Stack 2.0 after all CI checks passed. | |
| #1252 docs: update dependency sphinx stack to 2.0 | rockcraft | merged | Merged PR #1252 as caf0486f, upgrading and locking docs tooling to Sphinx Stack 2.0, removing Starter Pack references, and updating linter/link-checker settings. | |
| #496 build(docs): update Sphinx Stack to 2.0 | craft-cli | closed | Closed unmerged; superseded by the Starbase synchronization merge commit 21f2ac7, which brought the Sphinx Stack 2.0 docs tooling changes into main. | |
| #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. | |
| #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. | |
| #554 docs: update docs subproject readme | starbase | merged | PR #554 by medubelko merged as commit 0b67b94, rewriting docs/README.md with corrected, more detailed steps for updating the docs (Sphinx Stack) subproject; approved by 2 reviewers, all CI green. | |
| #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. |