Generate documentation automatically from our external API types and CLI commands

[luxas]

@fabriziopandini did half of this initially in kubernetes/website#6103, but I don't think those docs are updated automagically nor is the generation flow documented I think.

We should document how to generate those docs, along with API reference docs, in this repo (with link from https://github.com/kubernetes/kubeadm/blob/master/docs/release-cycle.md to whatever doc we create to make sure we do this if it has to be done manually for now).

cc @timothysc @neolit123

[neolit123]

@fabriziopandini did half of this initially in kubernetes/website#6103, but I don't think those docs are updated automagically nor is the generation flow documented I think

true.

the state at website is quite messy at the moment as there is still ongoing migration to the hugo website framework.

some of the old .mds contain HTML formatting that i cannot generate.
i've asked the same docs generation question here and on slack but i got no responses.
kubernetes/website#8617

also the whole automation of the process is quite unclear to me.
https://kubernetes.io/docs/home/contribute/generated-reference/kubernetes-components/
^ the update-imported-docs tool seems not hugo-ready and reports errors.

[luxas]

cc @kubernetes/sig-docs-maintainers ^

[Bradamant3]

Not sure whether y'all have seen the (old) planning doc, but in case it helps, it's here: https://docs.google.com/document/d/1w22y-C1YD1mmqqETxrQrCLnJpzwttscanddgvfYceYY/edit?usp=sharing

TL;DR: considerably more detail than the more general explanation of what's going on in the /contribute content on the docs website. Unfortunately, also not updated for Hugo. I have my guesses about fixes needed for update-imported-docs, but no time to look atm.

cc @steveperry-53

[neolit123]

so i was thinking about the example config files included on some of our pages like this one:
https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm-init/#config-file

the tooling to generate a master config example automatically and import them on the page could be kubeadm config print-default based and might come at some point, but i don't think it's realistic for 1.11.

in the meantime, this has to be edited manually and i was thinking to saying the following instead of including an inline example:

• "You can now use kubeadm config print-default to dump the default config to the terminal"
• link to godocs (https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm#MasterConfiguration)

[Bradamant3]

I agree that's an ugly big config file and it's a pain to maintain manually. But the godoc seems like poor UX -- it's the same fields with a whole lotta interspersed comments and so it's even harder for the reader to parse. If the idea behind the recent work on kubeadm is to improve the UX, sending folks to the godoc feels like a bad regression.

[neolit123]

we just had a talk about this at the sig-meeting and it appears that we are leaning towards godocs instead of maintaining an example inline config.

@timothysc

[neolit123]

so ideally i would need a final decision on how to proceed with this - e.g. what should we put in place of the config here:
https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm-init/#config-file

godocs links, kubeadm config print-default info, still use an inlined (alpha2) config for 1.11.
or perhaps a combination of the above.

[luxas]

I'm in favor for at least adding GoDoc as a compliment. We're actively improving the quality of the Godoc comments.
@Bradamant3 do you have a suggestion how to improve the UX but still not fall into the maintainability trap?

[Bradamant3]

Could we provide both for 1.11, and try to commit to "the tooling to generate a master config example automatically" for 1.12? That is, provide the config YAML and the godoc? For 1.11, I'd be willing to double-check the YAML to make sure it's current. (Just be sure to assign the related docs PR directly to me, and add the 1.11 milestone, or I'll never find it ...)

For this particular scenario, the problem is as much the sheer size of the object as it is the quality of the godoc comments. Harder to parse out the actual config file if you're a user.

[luxas]

@neolit123 sounds feasible to you?

[neolit123]

@luxas @Bradamant3
sounds good.

for 1.11 i'm adding:

• an inlined YAML - the output of kubeadm config print-default.
• a URL to the godocs for the same config.

For 1.11, I'd be willing to double-check the YAML to make sure it's current. (Just be sure to assign the related docs PR directly to me, and add the 1.11 milestone, or I'll never find it ...)

👍

[timothysc]

I'm a nak on generating for the main website vs. linking to godoc, b/c it will become a maintenance burden.

[Bradamant3]

By that token, any generated doc is a maintenance burden, or keeping docs up to date at all. Some maintenance burdens are part of life | software. Or we can ignore our users. (True there's no great UX solution here. But that doesn't mean we should make the UX worse with godoc only.)

[timothysc]

@neolit123 @luxas what are we doing here. I really want to avoid generated docs and instead link out to godocs where possible.

[neolit123]

@timothysc

so the old PR from Fabrizio that @luxas mentions in the OP is generating docs and including docs.
this has changed and we only have to submit PRs to <include> the generated .mds in website pages.

i will mention the above in:
https://github.com/kubernetes/kubeadm/blob/master/CONTRIBUTING.md

i think part of the idea here is to also be able to include automatically generated YAMLs for the master config, and other config types inside a website page, saying "here is the latest config" and we don't have to maintain it. i'm not sure how to proceed with that and this is 1.12.

until then, for this page specifically we need to replace the old config:
https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm-init/#config-file
with the one generated with kubeadm config print-default and also link to the alpha2 godocs for it.

[Bradamant3]

Folks, we've conflated two different issues here: the OP, which was about the current kubeadm docs and how we produce them, and a related but different issue specifically about generating the YAML at https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm-init/#config-file. @neolit123 has some good thoughts about the YAML, but let's set them aside for now. For the larger issue about the kubeadm docs:

Godocs are not an option here. We do not link to godocs from the /website repo. This is reference material for users/operators, not for devs, and the plan for the kubeadm docs was formulated and agreed upon over a period of months in 2017. It involved multiple iterations between dev and docs. Note also that historically sig-docs has been responsible for generating any required docs for the release. kubeadm is currently an exception because the process has not been adequately documented, and because the deliverables follow a new model, but these are the issues to address here, not whether we generate. sig-docs will need some help from sig-cluster-lifecycle in identifying and documenting the tooling and process. See inter alia kubernetes/website#8874

As #8874 also demonstrates, we've discovered recently that we do in fact need to include the generated docs for new kubeadm commands in PRs during the release cycle. This process is still being worked on.

cc @zacharysarah

[neolit123]

ok, we are leaving this issue only for the original topic:
Generate documentation automatically from our external API types and CLI commands

the two other ideas that came from this discussion are now logged in separate issues:
document the latest config at website under the kubeadm-init website page
#892
explain how we submit PRs for generated command docs in CONTRIBUTING.md
#893

[neolit123]

@timothysc @luxas please, close if see fit.