docs: make plugin links external refs
Metadata
Current evaluation
Closed unmerged: external intersphinx links cannot target unpublished pages. The maintainer proposed transforming links in the common-directory generator instead.
Resolution: closed not a bug
Reason: The author closed the PR on 2025-01-18 after confirming the approach was unsuitable. The identified flaw was that external references work only for already published pages, not pages introduced in the same change.
Evaluated by: mr-cal-bot
No scores available.
Issue body
Fixes the library side of CRAFT-3890.
- Makes the hosted Craft Parts docs an external source for this doc set.
- All interlinks in the plugin pages, which are often used by apps as modular docs, now use intersphinx and treats them as external links.
- Any potentially standalone pages should prefix references to other pages with `:external+craft-parts:ref:`. References to labels within the page can use simple `:ref:` like normal.
@lengau There's a flaw with this approach, though. Only already published pages can be linked to externally. If for example we add a new plugin page and want to link pages to it as part of the same code change, those links will break because the new page hasn't been published yet.
My thinking now is that the only straightforward approach is for the common dir generator script to transform the links after copying the files.
- [x] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
- [x] Have you added an entry to the changelog (`docs/reference/changelog.rst`)?
-----
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed not a bug | Closed unmerged: external intersphinx links cannot target unpublished pages. The maintainer proposed transforming links in the common-directory generator instead. | |
| stealth/space-bunny-alpha | — | closed not a bug | PR #965 (docs intersphinx-external plugin links, CRAFT-3890) closed unmerged by author medubelko: 'Closing – not an appropriate solution', since external refs only work to published pages. | |
| stealth/space-bunny-alpha | — | closed stale | Closed unmerged: external intersphinx links could only target published pages. The maintainer deemed the approach unsuitable and suggested transforming links after copying files instead. | |
| qwen/qwen3.6-35b-a3b | — | — | Closed without merging. The author identified a flaw where intersphinx external links only resolve for published pages, breaking links for new content. The approach was deemed inappropriate and abandoned. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Abandoned. The intersphinx approach for external plugin links was rejected due to a flaw where references to new, unpublished pages would break. The author closed the pull request without merging, noting the solution was not appropriate. |
Update history
No update history recorded yet.
Related issues
No related issues found above the similarity threshold.