← Back to issue list

docs: add, refactor, and reformat discourse docs feat. charmcraft

View original Github issue

Metadata

Project
charmcraft
Number
#2010
Type
pull request
State
merged
Author
tmihoc
Labels
Created
Updated
Closed

Current evaluation

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.

Suggested action:

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
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.
qwen3.6-35b-a3b-mtp-q6 Merged docs update adding, refactoring, and reformatting Discourse content for Charmcraft to ReadTheDocs. Linter issues resolved. Future structural changes may break links, with extensive maintenance deferred to post-migration.

Update history

No update history recorded yet.

Related issues

Issue Project State Summary Similarity
#471 config: add charm part to documentation (CRAFT-356) charmcraft merged Merged changes adding charm configuration documentation to the configuration schema. Approved by two reviewers with zero unresolved comments. Updated two files with 15 additions and one deletion. Resolves CRAFT-356.
76%
#2182 docs: add mention of `charmcraft promote` to manage-revisions.rst charmcraft merged Merged documentation update adding a reference to charmcraft promote in manage-revisions.rst and fixing a broken literalinclude directive in charmcraft-yaml-file.rst. Approved by two reviewers and integrated into the codebase.
75%
#2154 docs: replace occurrences of "charmcraft.yaml" and "recipe" charmcraft merged Merged documentation update replacing charmcraft.yaml and recipe with project or project file across 23 files. Approved by two reviewers after minor clarity feedback. Changes span +155/-159 lines.
75%
#242 Add init documentation for a gentle introduction to the charm operator charmcraft merged Merged PR adding starter docs to charmcraft init. Reviewer requested moving content to a Charmhub discourse wiki and linking it. Contributor adapted the change, and the PR was merged with the external link integrated.
72%
#2262 docs: hotfix for links syntax for charm docs examples charmcraft merged Merged following approval by three reviewers. The change corrected link syntax in the Manage charms documentation and added a Charmhub Discourse link. All required CI checks passed before integration.
72%
#188 Small text cleanups for README and charmcraft help charmcraft merged Merged text cleanups for the README and charmcraft help documentation. Approved by two reviewers, the change updates 13 files to improve clarity while preserving test compatibility.
72%
#2253 docs: add charm docs exemplars links charmcraft merged Merged after approval and CI checks. Added links to charm documentation exemplars to improve guidance. Updated one file with 34 additions and 5 deletions as part of a documentation standardization initiative.
72%
#2601 docs: Redo in-page links for: Mange charm revisions, Manage the current charmhub user, and Manage tracks charmcraft merged Merged documentation update fixing in-page links and adding introductory sentences to three how-to guides. Reviewer feedback was implemented before merge, completing a series for the Open Documentation Academy.
72%
#2241 Docs: Update 12-factor tutorials charmcraft merged Merged documentation updates to the 12-factor tutorials. Changes add UX tips for charmcraft and juju status, update rockcraft output, note faster builds, and condense architecture text. Approved by two reviewers and passed CI.
71%
#2589 docs: add Charmcraft 4.2 release notes charmcraft merged Merged pull request adding Charmcraft 4.2 release notes. The update adds 113 lines across two documentation files. Changes were reviewed, approved, and successfully integrated into the main branch.
70%