docs: add, refactor, and reformat discourse docs feat. charmcraft
Metadata
Current evaluation
Merged PR #2010 as commit a1a3d4b1, migrating Charmcraft content to RTD-ready docs, reformatting it, and separating Ops-related material.
Resolution: closed resolved
Reason: The approved documentation migration was merged as commit a1a3d4b1. Its cleanup also incorporated part of the build-error fix delivered by PR #2070.
Evaluated by: mr-cal-bot
No scores available.
Issue body
This PR adds all the juju.is/docs content featuring Charmcraft.
The content was originally formatted for Discourse; this PR reformats it to serve the RTD project the docs are destined for.
The content was also originally entangled with Ops content; this PR significantly refactors -- as well as clarifies and tries to complete -- everything to serve the stand-alone Charmcraft docs set it is destined for.
Issues that should be fixed in subsequent PRs:
- Everywhere: (1) (a) Links to juju.is will work, as even after moving docs out of there we'll have redirects; however, they should be updated. (b) Links to ops docs are empty -- they reference content I'm planning to move there post-refactoring; once we have them in place, which should be in the next few days and pre-official-Charmcraft-RTD-launch, we should add them in Charmcraft docs.
- Tutorial: The tutorial should also be offered in the "regular" flavor, that is, for apps that are not 12-factor. That flavor should also feature the publish step. (See, e.g., our old Kubernetes tutorial, which includes https://juju.is/docs/sdk/publish-your-charm-on-charmhub . PS If the Charmcraft tutorial starts featuring this, as it should, the old Kubernetes tutorial, which will be moved to the stand-alone Ops docs, can focus on just development, which is what Ops is really all about.)
- How-to guides: While this PR surfaces a lot more of Charmcraft and arguably a lot more clearly, there are still corners with cobwebs or gaps. These include: (1) Manage charms (12-factor app) -- I think this doc should be incorporated into the main Manage charms doc, which could have tabs for "regular', "django", etc. (This would align with plans for the juju.is/docs entrypoint into the "federated docs"). (2) The Manage parts doc, which is full of "TBA" -- i.e., has gaps. (3) The docs in "Misc", which are not well integrated with everything else here. (4) Maybe the Manage bundles doc, which doesn't by far tell the full story; given that we're phasing bundles out, it's also perhaps fine not to worry about this too much. (5) Commands `analyse` and `test` are not featured in any how-to guide.
- Reference: (1) The autogenerated `charmcraft` CLI command reference docs should have anchors on the template `command-charmcraft-x` and titles on the template "Command `charmcraft x`. This will not better align with existing practices in the Juju world but also results in more clarity when linking to the page using `{ref}`...`` (2) The various file reference docs should be as much as possible autogenerated from source (likely the source will have to be updated first) -- at the very least, file `charmcraft.yaml`. They may also need further clean-up. (3) The part docs are a bit of a mess. We should move any relevant content to the part docs, then link up to that and only keep in Charmcraft the material specific to Charmcraft docs, and then revisit that material as well to streamline it as much as possible (e.g., currently the dump plugin is documented in 3 places). (4) Charmcraft analyzers and linters -- this gives details on pack and analyse but it's not clear in what way it's useful to the reader, so we need to rethink.
- Explanation: We have nothing there. I didn't delete that section as I think there is potentially a topic we could have there -- e.g., Charmcraft in the bigger context of Starcraft (a clarification of the general design philosophy there and trends, maybe).
PS Some docs may have a Contributors list on the bottom, listing the Discourse handles of the contributors to date. We'll want to rethink how we do that.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged PR #2010 as commit a1a3d4b1, migrating Charmcraft content to RTD-ready docs, reformatting it, and separating Ops-related material. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged as commit a1a3d4b1: imported, refactored and reformatted Charmcraft Discourse docs for standalone Read the Docs, converting Markdown to RST and restructuring into docs/ (+9776/-129, 71 files). | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in commit a1a3d4b1: added, refactored and reformatted Charmcraft docs migrated from juju.is Discourse into a standalone Read the Docs set (+9776/-129, 71 files). | |
| stealth/space-bunny-alpha | — | closed resolved | Merged as commit a1a3d4b1: ported Charmcraft content from juju.is/docs Discourse into a standalone Read the Docs set, refactoring and converting Markdown to RST (+9776/-129, 71 files). Follow-up gaps tracked in later PRs. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in canonical/charmcraft#2010: added, refactored, and reformatted Charmcraft Discourse docs for standalone Read the Docs, including Markdown-to-RST conversion and structural cleanup. | |
| qwen/qwen3.6-35b-a3b | — | — | Merged documentation updates adding, refactoring, and reformatting Discourse content for Charmcraft into the ReadTheDocs project. Includes markdown to RST conversion, linter fixes, and structural improvements. Approved with noted future adjustments. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates adding, refactoring, and reformatting Discourse content for Charmcraft to support ReadTheDocs. Includes cleanup and codespell fixes. Approved with caveats that future structural changes may break links. |
Update history
No update history recorded yet.
Related work
-
Related To:
canonical/charmcraft#2070
(confidence 98%)
The author confirmed that the final cleanup included part of this merged documentation build fix.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2299 docs: fix formatting issues | charmcraft | merged | Merged docs formatting fixes for local documentation builds in charmcraft#2299 via commit 5ffb80fe; two files changed (+3/-1). | |
| #2748 docs: improve charm naming docs, with links to detailed guidance | charmcraft | merged | Docs PR #2748 merged (commit 0389aeb4): rewrote charm naming guidance in the charmcraft.yaml reference and manage-charms how-to, replacing inline best-practice notes with links to the Ops docs. Fixes #2582; relied on canonical/operator#2610. | |
| #471 config: add charm part to documentation (CRAFT-356) | charmcraft | merged | Merged PR #471 via commit e0b18661, documenting the charm part in the configuration schema for CRAFT-356. | |
| #2038 docs: prepare 3.3 changelog | charmcraft | merged | Merged documentation preparing Charmcraft's 3.3 changelog in PR #2038 (commit 5037fcb1), updating four files with 48 additions and 10 deletions. | |
| #2154 docs: replace occurrences of "charmcraft.yaml" and "recipe" | charmcraft | merged | Merged PR #2154 (a6ccb3d4) updated 23 documentation files to use “project” or “project file” instead of “charmcraft.yaml” and “recipe.” | |
| #2186 docs: fix build errors | charmcraft | merged | Merged as charmcraft/charmcraft#2186 in commit 42f42bd2, fixing the targeted docs build error. Remaining transclusion problems were addressed separately in canonical/craft-parts#1021. | |
| #2795 docs: improve `charmcraft clean` command documentation | charmcraft | closed | Closed unmerged; maintainer @lengau rejected the proposed charmcraft clean documentation as subpar, and no documentation commit or replacement PR landed. | |
| #2128 docs: add anchors and fix a few small things | charmcraft | merged | Docs PR merged as commit e880b4bd: added intersphinx anchors (e.g. _manage-charms, _initialise-a-charm) for Ops/Juju linking, retitled 'Set up Charmcraft' to 'Manage Charmcraft', expanded content, and fixed a rendering error. | |
| #2300 docs: update "manage configurations" | charmcraft | merged | Docs PR #2300 merged as commit dc4bedb1: updated Charmcraft links to operator's renamed "Manage configuration" howto and renamed the section heading to "Manage the app configuration" per maintainer request. | |
| #2734 docs: improve versioning logic | charmcraft | merged | Merged as 5fb6af27, updating docs versioning so the unversioned/latest documentation is labeled “Charmcraft dev documentation.” |