docs: searching for build-packages yields no useful results
Metadata
Current evaluation
Docs search for "build-packages" ranks the snapcraft.yaml reference low because Sphinx splits hyphenated terms. Maintainer medubelko diagnosed the ranking cause, found no Sphinx weighting fix, and deferred it to a future theme/search-provider migration.
Suggested action: keep open
Reason: The maintainer explicitly confirmed the report is real — "The search does return the `build-packages` key in the `snapcraft.yaml` reference, but it's buried in the bottom half of the results" — and identified the cause as the default Sphinx search treating "build-packages" as two separate terms without prioritising the matching section name. The issue is triaged and valid, but the maintainer states "I don't know of a solution" since the default Sphinx search offers no per-page term weighting, and no fix exists in the repo: docs/conf.py only sets html_theme_options and sitemap excludes, with no search configuration to change. The second claim is partly inaccurate: docs/reference/snapcraft-yaml.rst:383 does document the key as "PartSpec build_packages" and docs/how-to/crafting/manage-dependencies.rst:52 documents it in a key/description table, so the content exists but is not surfaced prominently by search. Kept open because the maintainer tied reassessment to a planned theme migration rather than rejecting it.
Evaluated by: mr-cal-bot
Issue body
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha |
Impact:
25
Quick Win:
4
Complexity:
60
Confidence:
82
Actionability:
45
|
keep open | Docs search for "build-packages" ranks the snapcraft.yaml reference low because Sphinx splits hyphenated terms. Maintainer medubelko diagnosed the ranking cause, found no Sphinx weighting fix, and deferred it to a future theme/search-provider migration. | |
| qwen/qwen3.6-35b-a3b |
Impact:
35
Quick Win:
12
Complexity:
45
Confidence:
75
Actionability:
60
|
keep open | Documentation search for "build-packages" returns irrelevant results because Sphinx treats hyphenated terms as separate words. Maintainer acknowledged the issue and noted a future search provider migration may resolve it. | |
| qwen/qwen3.8-27b |
Impact:
25
Quick Win:
14
Staleness:
50
Complexity:
45
Confidence:
75
Support Request:
10
|
keep open | Snapcraft docs search for 'build-packages' returns poor results due to Sphinx default search treating hyphenated terms as separate words. Maintainer triaged, identified root cause, and deferred fix to a planned theme/search-provider migration. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
40
Complexity:
20
Confidence:
85
Support Request:
10
|
keep open | Documentation search for build-packages returns poor results due to Sphinx tokenization. A maintainer identified the root cause and deferred resolution to a planned search provider migration later this year. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
45
Complexity:
20
Confidence:
85
Support Request:
0
|
keep open | Documentation search fails to surface build-packages due to Sphinx tokenization treating it as two words. Maintainer acknowledged limitation and deferred fix to future search provider migration. |
Update history
No update history recorded yet.
Related work
-
Related To:
snapcraft#5452
(confidence 55%)
Commit b71a0df22 'docs: migrate Build and staging dependencies (#5452)' created docs/how-to/crafting/manage-dependencies.rst, which now documents build-packages in a key/description table, but the commit does not address search discoverability of the key.
-
Related To:
snapcraft#5440
(confidence 50%)
Commit 47574a240 'docs: reorganise pages (#5440)' restructured the docs tree; the reorganised reference page places build_packages under PartSpec but search relevance was not a stated goal of the change.
Related issues
No related issues found above the similarity threshold.