← Back to issue list

Reference docs: Separate "library developer/user" content from "craft user" content

View original Github issue

Metadata

Project
craft-parts
Number
#750
Type
issue
State
open
Author
thp-canonical
Labels
—
Created
Updated
Closed
—

Current evaluation

Request to restructure craft-parts reference docs by audience (craft YAML user vs Python library user) and split 'Parts and steps' into Environment variables / Output directories. Untriaged, no labels or comments; the flat structure still exists in current docs.

Suggested action: needs triage

Reason: The issue is a legitimate docs restructure request but shows no maintainer engagement — no labels, no comments, no assignee — so it needs triage. I verified docs/reference/index.rst still lists the flat structure (actions, exceptions, infos, lifecycle_manager, part_properties, parts_steps, plugins, reference, changelog) and parts_steps.rst still contains the Permissions/Steps sections the issue asks to move, so the request remains applicable rather than stale.

Impact: 25 Quick Win: 13.75 Staleness: 70 Complexity: 45 Confidence: 72 Support Request: 0

Issue body

### What needs to get done Looking at https://canonical-craft-parts.readthedocs-hosted.com/en/latest/reference/, the sub-sections have a different audience/content and are mixed: * Actions: Python * Exception: Python * Project information: Python * Lifecycle manager: Python * Part properties: YAML * Parts and steps: (contains 1 part property + build-time environment/directory information) * Plugins: YAML * Package reference: Python * Changelog: Meta "Parts and steps" is special: * [permissions](https://canonical-craft-parts.readthedocs-hosted.com/en/latest/reference/parts_steps.html#permissions) should probably be moved to "Part properties" * [steps](https://canonical-craft-parts.readthedocs-hosted.com/en/latest/reference/parts_steps.html#steps) could probably be split into a top-level "Environment variables" item (from "Step execution environment") and "Output directories" item (from "Step output directories") It might make sense to have the "Environment variables" and "Output directories" as top-level items in the Reference section ("next to" Python, YAML and Changelog), since these are not directly related to either Python or YAML, but rather to the run-time shell scriptlets (those could then also be linked from the `*-override` docs, see #659). Here's a proposed additional layer of structuring/grouping, e.g.: * YAML * Part properties * Plugins * ... * Build * Environment variables * Output directories * Python Library * Actions * Exception * Project information * Lifecycle manager * Package reference * ... * Changelog Instead of "YAML", maybe "Craft YAML", "Craft Language" or whatever exists as name for the `*craft.yaml` files might be used, of course. Also, moved the "Python Library" section to the bottom, since there's probably more "craft users" / end users than library users, so the YAML/Build parts should probably be presented more prominently. ### Why it needs to get done When I'm using craft-parts as a Python library, I'm looking for different documentation than when I'm using craft-parts as an end user, and it's usually one or the other, seldomly both at the same time. Being able to drill down to the current "mode" I'm in will help avoid ending up on the wrong part of the documentation.

Evaluation history

Date Model Scores Action Summary
qwen/qwen3.8-27b
Impact: 25
Quick Win: 13.75
Staleness: 70
Complexity: 45
Confidence: 72
Support Request: 0
needs triage Request to restructure craft-parts reference docs by audience (craft YAML user vs Python library user) and split 'Parts and steps' into Environment variables / Output directories. Untriaged, no labels or comments; the flat structure still exists in current docs.
qwen/qwen3.6-35b-a3b
Staleness: 92
Complexity: 35
Confidence: 75
Support Request: 5
needs triage Proposes restructuring reference docs to separate library developer (Python) and craft user (YAML/Build) content. Currently unlabelled, zero maintainer comments, and inactive for over two years.
qwen3.6-35b-a3b-mtp-q6
Staleness: 85
Complexity: 15
Confidence: 80
Support Request: 10
needs triage Proposal to restructure reference documentation by separating library developer content from craft user content. Unlabelled and has received no maintainer feedback in over a year.
qwen3.6-35b-a3b-mtp-q6
Staleness: 90
Complexity: 30
Confidence: 85
Support Request: 10
needs triage Restructure reference docs to separate Python library developer content from Craft YAML end-user content. Groups materials by audience to improve navigation. Open, zero comments, inactive for over a year, requires triage and assignment.

Update history

No update history recorded yet.

Related work

  • Related To: craft-parts#659 (confidence 75%)

    Issue body explicitly cross-references #659 ('those could then also be linked from the *-override docs, see #659'); #659 is an open, untriaged request to document/cross-reference override-* step working directories and environment variables, the same docs area.

Related issues

No related issues found above the similarity threshold.