Charm pages

[evilnick]

No description provided.

[evilnick]

A variant -

[hyperbolic2346]

🍲

[evilnick]

@tvansteenburgh These are the current variants for the semi-auto-generated charm pages:

Option 1 - Write out in full - This is very similar to the current pages on jaas.ai, it just lists all the config options with a header, type, default and description.

Pros - easy to generate reliably, easy to search, somewhat easy to mix content
Cons - it is a big page. For the more complex charms, it will be frighteningly long and will probably need a TOC.

preview: https://5e319f8d06ca5b00085d48a2--cdk-docs-next.netlify.com/kubernetes/docs/charm-kubernetes-worker-a

---

Option 2 - tables - This is a semi-intelligent table layout where bigger entries are linked out to notes below.
Pros - quite easy to see most things at-a-glance, more compact than option 1
Cons - slightly confusing to go back and forth between the table and the notes

preview: https://5e319f8d06ca5b00085d48a2--cdk-docs-next.netlify.com/kubernetes/docs/charm-kubernetes-worker-b

---

Option 3 - foldouts - This hides all the details behind an expander.

Pros - very compact, even for larger amounts of stuff. Doesn't need a TOC
Cons - not searchable in page (things can only be found if they are displayed), may introduce some challenges for autogeneration.

preview: https://5e319f8d06ca5b00085d48a2--cdk-docs-next.netlify.com/kubernetes/docs/charm-kubernetes-worker-c

[kwmonroe]

My $0.02, the cons for options 1 and 3 are annoying enough to rule them out.

For option 2, is it possible to generate anchors for the See notes links and then add a Back to table link beside each note that takes the user back to the respective table anchor?

Also for 2, is it possible to put all the notes under a collapsed Notes foldout? If the See notes link can automatically unfold and take the user to the appropriate note, having all the notes collapsed by default would would help shorten the page.

Even if the above aren't feasible, I like option 2 the best.

[johnsca]

I don't find the cons from option 3 as big of a deal as @kwmonroe, since in theory the config option name ought to be sufficiently searchable, and I like the compactness of it. But I'm also fine with option 2 + his suggestion on reverse anchors.

[tvansteenburgh]

@evilnick Thanks for the work that's gone into this so far, and for presenting multiple options. I personally prefer option 2, and it's not close - I think it looks the best. I also like @kwmonroe's idea for the reverse anchors to take one back to the table.

Originally I was thinking that we'd need to be able to add content to accompany the charm config descriptions. Like longer explanations, examples, etc. - stuff that would help explain how to use that config option, but that was too lengthy to put in the actual description field in config.yaml.

But now that I see how nicely the descriptions are rendered, I'm thinking we should in fact put everything in the description field in config.yaml. Interested in others' thoughts on this.

[evilnick]

The core charms have all been updated. It would be helpful if you could report any weirdness in the tables or the notes below as a comment here

I have made a temporary index page so the easiest way to see each page is from here:
https://deploy-preview-296--cdk-docs-next.netlify.com/kubernetes/docs/charm-reference

The rest of the page is populated with the current README files from the charm store, some of them will need a bit of work also but for now I want to get the tables sorted.

[evilnick]

Oh, N.B., some of them don't have config options (e.g. kata, easyrsa) so there are no tables on those pages

[tvansteenburgh]

Reviewed charm-aws-iam, charm-easyrsa, charm-keepalived.

[johnsca]

Reviewed the integrator charms. They all had out-dated references to CDK, but it was easier to just apply the edits directly than comment on each one, so they're all fixed. +1 for those.

[johnsca]

I think I understand why this config section comes before the examples whereas the other charms have the config last, but it was a bit jarring when flipping between them to see the config reference mixed into the middle. I don't know that there's a reasonable way to get that arrangement for this particular charm, though, because of the additional required config.

[kwmonroe]

Not sure if these links were skipped on purpose, but there are a couple that don't point to the respective charm-$foo pages.

[kwmonroe]

We're inconsistent with the # Contact section in a few of our charms. Most don't have it, so I think these should be removed across the board. They either point to these docs or a charmstore readme, which doesn't seem very useful considering the person reading these pages is already here.

[kwmonroe]

Requesting changes for the k8s-master charm. Mostly outdated links and CDK vs CK issues.

[kwmonroe]

A few tweaks for k8s-worker. Match k8s-master descriptions where relevant and rephrase some confusing bits.

[Cynerva]

I've re-reviewed the Flannel, Calico, Canal and Tigera Secure EE pages. Looks like all my concerns were indeed resolved. Thanks!

[kwmonroe]

I made a quick update directly to this branch for the k8s-master resources link. All other issues with my charms (charm-docker, charm-docker-registry, charm-kubeapi-load-balancer, charm-kubernetes-[master|worker]) have been resolved. Thanks!