Repository navigation
docs: suggest reusing index.rst first sentence for llms_txt_description - #638
Conversation
The scaffold comment invited child repos to write a fresh blurb for llms_txt_description, which drifts from the home page over time. Point authors at reusing the first sentence of docs/index.rst instead, matching the preference from the craft-parts review. Closes canonical#603 Signed-off-by: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com>
There was a problem hiding this comment.
🟢 Approval recommended
Comment-only documentation change with no unresolved issues.
No open issues 🎉
What changed in this PR
Updates documentation scaffold guidance to reuse the first sentence from docs/index.rst for llms_txt_description, preventing description drift.
Changes:
- Replaces the generic description prompt with reuse guidance.
- Warns against maintaining a separate hand-authored description.
| File | Description |
|---|---|
docs/conf.py |
Updates llms_txt_description scaffold comments. |
Review effort: Lite
There was a problem hiding this comment.
Hi @Shahzeb-DataEngineer :)
I think this sort of does both behaviors instead of preferring one or the other. This says "reuse the existing content", but also "you must mutate the existing content to fit this template."
How about instead suggesting a preference for the existing content, and providing the existing example as something to be used if there isn't any existing content to use in its place?
|
Thanks for the feedback, that makes sense. Updated the comment to prefer reusing the existing home page sentence as-is, with the example kept only as a fallback for when there is no suitable existing content. Let me know if this reads better now. |
|
Thank you both for the reviews and approvals. Happy to make any further tweaks if needed. |
Description
The scaffold comment invited child repos to write a fresh blurb, which drifts from the home page over time. This updates the scaffold comment to direct authors to reuse the first sentence of instead, and notes that a second hand-authored description will drift.
This matches the preference from the craft-parts review referenced in the issue (craft-parts now carries the home page sentence with no TODO inviting a fresh blurb).
Comment-only change to the scaffold; no behaviour change.
Related issue
Closes #603