feat(docs)!: rework bundling of shared docs
Metadata
Current evaluation
Merged in 841244bd: reorganized reusable documentation under docs/common/craft-parts/ so Craft Parts and downstream applications can reference shared paths without conflicts.
Resolution: closed resolved
Reason: PR canonical/craft-parts#688 was approved and merged as commit 841244bd, completing the shared-documentation restructuring.
Evaluated by: mr-cal-bot
No scores available.
Issue body
This PR re-organizes the docs/ folder to share *most* of the rst files. Moving forward, the expectation is that new content will be written inside of docs/common/craft-parts/ if there is any expectation at all that downstream applications will want to include it in their own docs. The idea is to keep to the /common/craft-parts/ folder so that both Craft Parts and applications can refer to the docs using the same path, without overlaps/conflicts.
Not everything is shared - some docs are kept in Craft Parts as they are not meant to be consumed by users of downstream applications. Some examples:
- Class references to Craft-parts internals;
- Docs about using ``craft-parts`` directly from the command line;
- "Meta documentation" about documenting the library itself;
- Front-page and tables of contents that structure Craft Parts' own docs.
- [ ] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
-----
This PR is split over multiple commits to simplify review. The first commit has most of the changes but they are all shuffling files around.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged in 841244bd: reorganized reusable documentation under docs/common/craft-parts/ so Craft Parts and downstream applications can reference shared paths without conflicts. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in commit 841244bd (#688), reorganizing shared documentation under docs/common/craft-parts/ for consistent downstream reuse. | |
| qwen/qwen3.6-35b-a3b | — | — | Merged a documentation reorganization that consolidates shared RST files into a common craft-parts directory while keeping internal and application-specific content separate. Approved by two reviewers and passed CI. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged docs reorganization sharing most RST files via a common path for downstream applications. Craft Parts internals and CLI guides remain local. Split into multiple commits for review. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1939 feat(docs): add craft-parts common documentation | charmcraft | merged | Merged as 534c028f, adding shared craft-parts documentation across eight files and laying groundwork for Python and Poetry plugin guides in #1940. | |
| #4679 refactor(docs): use more docs from craft-parts | snapcraft | merged | Merged #4679 as b8c9a17dc, replacing duplicated Snapcraft docs with direct craft-parts TOC references or includes for shared content. | |
| #920 docs: add common page 'reuse packages between builds' | craft-application | merged | Merged in canonical/craft-application#920 (commit 062eef48), adding shared docs on reusing packages between builds and sphinx-substitution-extensions. | |
| #4635 feat(docs): pull in content from craft-parts | snapcraft | merged | Merged #4635, importing craft-parts documentation into Snapcraft across 21 files; landed as commit 055a93543 after three approvals. | |
| #501 feat(docs): pull in content from craft-parts | rockcraft | merged | Merged via commit 3f934304, importing Craft Parts content into 18 Rockcraft documentation files (+103/-17). | |
| #247 docs: include some docs from craft-parts | rockcraft | closed | PR pulling craft-parts docs into rockcraft was left unmerged and closed as redundant; the same docs refactor landed instead via rockcraft#515 (commit 5c2263f1, "refactor(docs): use more docs from craft-parts"). | |
| #294 docs: import Craft Parts documentation fragments | rockcraft | merged | Merged Craft Parts documentation fragment imports in commit 2148b5be, updating six files (+71/-23) after reviewer approval. | |
| #1021 docs: prevent transclusion issues | craft-parts | merged | Merged canonical/craft-parts#1021, updating two documentation files to prevent transclusion problems in downstream applications. | |
| #515 refactor(docs): use more docs from craft-parts | rockcraft | merged | Merged #515 refactored Rockcraft docs to reuse Craft Parts pages via direct TOC links or local includes (commit 5c2263f1). | |
| #314 docs: clean up references to Craft Parts | rockcraft | closed | Craft Parts documentation cleanup was folded into canonical/rockcraft#308, merged as commit 13bf8368, and #314 was closed. |