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

tmihoc · 2024-11-29T11:56:29Z

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.

lengau · 2024-11-29T17:52:12Z

We can ignore the test failures, but the linter that's failing is codespell and is related to these changes: https://github.com/canonical/charmcraft/actions/runs/12084317065/job/33699249108?pr=2010#step:6:637

docs/common/craft-parts

tmihoc · 2024-12-02T15:17:35Z

We can ignore the test failures, but the linter that's failing is codespell and is related to these changes: https://github.com/canonical/charmcraft/actions/runs/12084317065/job/33699249108?pr=2010#step:6:637

I think I've addressed all of these now.

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.md

lengau

Looks good, thanks!

lengau · 2024-12-03T19:11:19Z

Hey, so pandoc can convert these markdown files to rst: pandoc -s <file>.md -o <file>.rst

medubelko · 2024-12-12T17:19:59Z

The following pages have extensive maintenance planned post-migraiton, so they don't need detailed review:

reference/extensions/charmcraft-extension-django-framework
reference/extensions/charmcraft-extension-fastapi-framework
reference/extensions/charmcraft-extension-flask-framework
reference/extensions/charmcraft-extension-go-framework
howto/manage-12-factor-app-charms
tutorial/write-your-first-kubernetes-charm-for-a-django-app
tutorial/write-your-first-kubernetes-charm-for-a-fastapi-app
tutorial/write-your-first-kubernetes-charm-for-a-go-app

I'm breaking down the content from PR #2010 into smaller chunks. This is "How to manage 12-factor app charms" converted to RST: https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md The main differences from the Markdown version: - Uses tabs instead of dropdowns (matching the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/) - "See also" blocks are added as cards

This reorganises the part reference in line with #2010

medubelko

Approving without review. If we merge this, we can resolve any code issues during separate RST conversion tasks.

I'm breaking down the content from PR #2010 into smaller chunks. This is "How to manage 12-factor app charms" converted to RST: https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md The main differences from the Markdown version: - Uses tabs instead of dropdowns (matching the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/) - "See also" blocks are added as cards

The current Flask tutorial: https://juju.is/docs/sdk/write-your-first-kubernetes-charm-for-a-flask-app This PR will move the tutorial off of Discourse and Charm SDK and onto the Charmcraft RTD. --------- Co-authored-by: Michael DuBelko <[email protected]> Co-authored-by: Alex Lowe <[email protected]>

docs/reference/files/file-charmcraft-yaml.rst

lengau · 2024-12-19T19:10:30Z

docs/tutorial/index.rst

@medubelko please look at this file

This one is encroaching on CRAFT-3702, therefore I don't think we need to exercise a huge amount of discretion at this point. I've sent you the landing page exemplar we use.

docs/reference/files/file-libname-py.md

sergiusens · 2024-12-19T19:19:29Z

We've decided to merge this this week, with the caveat that we will make changes to the structure which has the potential to break links

medubelko

I left comments for the files you requested.

medubelko · 2024-12-19T23:06:33Z

docs/reference/files/file-charmcraft-yaml.rst

@@ -0,0 +1,901 @@
+.. _file-charmcraft-yaml:
+.. highlight:: yaml


Since highlight acts as a switch, I think the code would be easier to read if it were placed immediately before the first block that uses it.

That's pretty unintuitive to me - if I'm looking for why a block is highlighted in an unexpected manner, I'm going to check that block (which is likely not the first block in the page, especially for reference pages like this), then the directives at the very top of the page, then the global highlight_language configuration.

A highlight directive somewhere in the middle of a file would be highly unappreciated, much like an import coming between two class definitions in a source file. Worse still would be a switch of the highlight directive mid-file, which would be a form of code smell that this document is about two different things (and thus should be broken up into multiple pages), since in cases where one needs to change the highlight language a code-block can set its own language as a one-off.

medubelko · 2024-12-19T23:07:38Z

docs/reference/files/file-charmcraft-yaml.rst

+.. highlight:: yaml
+
+``charmcraft.yaml``
+*******************


A nitpick, but I've been trying to stick to the heading conventions recommended by the style guide.

Thanks - yeah, @tmihoc pointed this out to me yesterday too, which was actually my first knowledge about us having an rST style guide specifically.

docs/reference/files/file-charmcraft-yaml.rst

medubelko · 2024-12-19T23:18:49Z

docs/reference/files/file-charmcraft-yaml.rst

+    The full list of keys is defined in the Charmcraft project (but this implies upstream keys from craft-application):
+    https://github.com/canonical/charmcraft/blob/3.2.0/charmcraft/models/project.py#L381-L1070
+
+    Technically, the only key required upfront is type. But then, depending on what you choose, other keys become required as well. (The required keys are the ones that are set to a value, unless that value is a pydantic.Field that doesn't have either a default or a default_factory parameter)


We've been very consistent about 2 spaces for indentation. You may recall we recently discussed switching my YAML examples in Snapcraft back to 2 spaces.

The current configuration for markdown and rst in starbase is the global default of indent_size = 4, so if we want to change that well need to change the standard and the existing documentation files, including in Starbase itself.

The indent size of 2 for YAML files has been in Starbase for 22 months.

I've created an issue on Starbase so we can get clarification for everything that needs changing here.

docs/reference/files/file-charmcraft-yaml.rst

docs/reference/files/file-libname-py.md

medubelko · 2024-12-19T23:57:06Z

docs/tutorial/index.rst

This one is encroaching on CRAFT-3702, therefore I don't think we need to exercise a huge amount of discretion at this point. I've sent you the landing page exemplar we use.

docs/reference/files/file-libname-py.rst

Co-authored-by: Michael DuBelko <[email protected]>

medubelko self-requested a review November 29, 2024 17:41

lengau reviewed Nov 29, 2024

View reviewed changes

docs/common/craft-parts Outdated Show resolved Hide resolved

tmihoc force-pushed the rtd-docs branch 2 times, most recently from b86dd66 to b69eb9d Compare December 2, 2024 15:16

lengau reviewed Dec 2, 2024

View reviewed changes

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.md Outdated Show resolved Hide resolved

tmihoc force-pushed the rtd-docs branch from b69eb9d to 11f8c9e Compare December 3, 2024 08:25

lengau approved these changes Dec 3, 2024

View reviewed changes

lengau mentioned this pull request Dec 17, 2024

docs: add "How to manage 12-factor app charms" #2048

Open

lengau added a commit that referenced this pull request Dec 17, 2024

docs: reorganise the Part reference

773a856

This reorganises the part reference in line with #2010

lengau mentioned this pull request Dec 17, 2024

docs: reorganise the Part reference #2049

Closed

lengau force-pushed the rtd-docs branch from 737976c to 11f8c9e Compare December 17, 2024 20:11

medubelko approved these changes Dec 17, 2024

View reviewed changes

tmihoc force-pushed the rtd-docs branch from 1cdebeb to 6a4dac4 Compare December 19, 2024 15:17

lengau requested a review from sergiusens as a code owner December 19, 2024 15:29

tmihoc and others added 8 commits December 19, 2024 10:30

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

ed318e0

docs: convert howtos to rst

5ed8111

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

08ba2b8

docs: replace actions.yaml markdown with rst

6b4a14f

docs: move charmcraft.yaml file reference to rst

5e30dc3

docs: update links

1db6b04

docs: swap config.yaml reference to RST

e60edb9

docs: convert file-bundle-yaml.md to rst

f9f6a3b

lengau force-pushed the rtd-docs branch from 3a62c95 to f9f6a3b Compare December 19, 2024 15:31

tmihoc and others added 7 commits December 19, 2024 16:48

docs: remove md files already converted to rst

2c31ea5

docs: fix build breakage

7e7b1d6

docs: migrate contributing.md reference to rst

6f2f2ac

docs: replace files index with rst

f6aa440

docs: move dispatch file to rst

d8e2d77

docs: move icon.svg docs from markdown to rst

1df7ac4

docs: change <libname>.py to rst

b0965c1

lengau reviewed Dec 19, 2024

View reviewed changes

docs/reference/files/file-charmcraft-yaml.rst Show resolved Hide resolved

lengau reviewed Dec 19, 2024

View reviewed changes

docs/reference/files/file-libname-py.md Outdated Show resolved Hide resolved

lengau added 2 commits December 19, 2024 16:36

docs: fix linting issues

9d2d880

chore: make editorconfig match rst line length

a4b774f

medubelko requested changes Dec 19, 2024

View reviewed changes

lengau mentioned this pull request Dec 20, 2024

Change indentation format for RST (and possibly Markdown?) files canonical/starbase#307

Open

lengau reviewed Dec 20, 2024

View reviewed changes

docs/reference/files/file-libname-py.rst Outdated Show resolved Hide resolved

fix: pr suggestions

3f07d23

Co-authored-by: Michael DuBelko <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

tmihoc commented Nov 29, 2024 •

edited

Loading

lengau commented Nov 29, 2024

tmihoc commented Dec 2, 2024

lengau left a comment

lengau commented Dec 3, 2024

medubelko commented Dec 12, 2024

medubelko left a comment

lengau Dec 19, 2024

medubelko Dec 19, 2024

sergiusens commented Dec 19, 2024

medubelko left a comment

medubelko Dec 19, 2024

lengau Dec 20, 2024

medubelko Dec 19, 2024

lengau Dec 20, 2024

medubelko Dec 19, 2024

lengau Dec 20, 2024 •

edited

Loading

lengau Dec 20, 2024

medubelko Dec 19, 2024

		@@ -0,0 +1,901 @@
		.. _file-charmcraft-yaml:
		.. highlight:: yaml

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

Are you sure you want to change the base?

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

Conversation

tmihoc commented Nov 29, 2024 • edited Loading

lengau commented Nov 29, 2024

tmihoc commented Dec 2, 2024

lengau left a comment

Choose a reason for hiding this comment

lengau commented Dec 3, 2024

medubelko commented Dec 12, 2024

medubelko left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sergiusens commented Dec 19, 2024

medubelko left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lengau Dec 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tmihoc commented Nov 29, 2024 •

edited

Loading

lengau Dec 20, 2024 •

edited

Loading