Missing links to generated kubeadm pages

[tengqm]

This is a Bug Report

Problem:

The following pages under docs/reference/setup-tools/kubeadm/ are currently manually maintained.

kubeadm-alpha.md
kubeadm-config.md
kubeadm-init-phase.md
kubeadm-init.md
kubeadm-join-phase.md
kubeadm-join.md
kubeadm-reset-phase.md
kubeadm-reset.md
kubeadm-token.md
kubeadm-upgrade-phase.md
kubeadm-upgrade.md
kubeadm-version.md

It is expected that each generated page under docs/reference/setup-tools/kubeadm/generated/ has at least one link to it from these files, otherwise it becomes orphaned.

The following pages are orphaned:

docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_certs.md
docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_certs_generate-csr.md
docs/reference/setup-tools/kubeadm/generated/kubeadm_init_phase_kubelet-finalize.md
docs/reference/setup-tools/kubeadm/generated/kubeadm_init_phase_kubelet-finalize_all.md
docs/reference/setup-tools/kubeadm/generated/kubeadm_init_phase_kubelet-finalize_experimental-cert-rotation.md
docs/reference/setup-tools/kubeadm/generated/kubeadm_upgrade_node_phase_preflight.md

Proposed Solution:

Add links to these generated pages.

[sftim]

Thanks

/sig cluster-lifecycle /triage accepted /kind cleanup /language en /priority backlog

[sftim]

We could instead use Docsy's automatic list generation, and add descriptions to each page (eg, to the front matter of /docs/reference/setup-tools/kubeadm/generated/kubeadm-alpha.md).

[neolit123]

docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_certs.md docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_certs_generate-csr.md

kubeadm alpha certs is marked as deprecated in 1.20, so i assume the generation for it will be skipped (the command will be hidden). the command is graduated as kubeadm certs.

the graduation and missing generate-csr is covered here: https://github.com/kubernetes/website/pull/24410

Add links to these generated pages.

the rest are indeed missing. is there a way to catch this during CI of website PRs?

We could instead use Docsy's automatic list generation, and add descriptions to each page (eg, to the front matter of /docs/reference/setup-tools/kubeadm/generated/kubeadm-alpha.md).

i don't know how Docsy works, but would appreciate ideas around this as manually maintaining the subcommands is not ideal.

[sftim]

Hmm, looking at this a bit more just setting a description might not be enough. The current pages are a mix of generated and manually written ones.

There are a few different ways to combine these. It sounds like extending the generator could help there - that could be a separate feature request against the generator code, eg to warn if a subcommand isn't documented as expected.

[neolit123]

i think we could do the following:

• on the main pages that are currently manually maintained for kubeadm config etc, "include" the parent generated page (https://github.com/kubernetes/website/blob/master/content/en/docs/reference/setup-tools/kubeadm/kubeadm-config.md)
• the generated page could have relative hyperlinks to the generated pages of sub-sub-commands (e.g. kubeadm_config.md having links to kubeadm_config_*.md, and this can reveal the whole tree relation between sub-commands and sub-sub-commands (and deeper).
• this means that ideally the generated pages should have a title on top too: https://github.com/kubernetes/website/blob/master/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config.md https://github.com/kubernetes/website/blob/master/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_view.md and a section for the sub-commands.

EDIT: and if the kubeadm commands lack sufficient information it should be added in the source code of kubeadm.

would navigating around /generated pages sound like a good idea? e.g. https://kubernetes.io/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_view/

[sftim]

@neolit123 that sounds like a plan.

BTW, if the generator has the smarts to add metadata into generated Markdown (eg: a YAML list of subcommands, in front matter) then we can implement a Hugo layout that automatically processes that metadata into HTML. I can probably help with this approach, if selected.

So you have options: more code in the docs generator, or less docs generator code but then more work for the Go templating.

[neolit123]

BTW, if the generator has the smarts to add metadata into generated Markdown (eg: a YAML list of subcommands, in front matter) then we can implement a Hugo layout that automatically processes that metadata into HTML. I can probably help with this approach, if selected.

given the subcommand relation is already described by the filenames:

kubeadm_config
kubeadm_config_foo
kubeadm_config_foo_bar

can Hugo just process that instead of requiring the metadata to be part of the markdown?

So you have options: more code in the docs generator, or less docs generator code but then more work for the Go templating.

i think i'm leaning towards the first option, but that is because i don't know much about Hugo.

if the docs team and @tengqm prefer the second option, we should go for that.

[sftim]

given the subcommand relation is already described by the filenames … can Hugo just process that instead of requiring the metadata to be part of the markdown?

I'd rather not hard-code in a full path into the layout code, because I think that could be fragile when it doesn't need to be.

If we can set some marker eg content_type: generated in the front matter for each page where that applies, I think I could persuade Hugo to work out the rest of the details.

[tengqm]

Let's fix it by following the current practices. We can file a new issue to track the improvement/automation.

[neolit123]

LGTMed the PR, will add notes to https://github.com/kubernetes/website/issues/24558 thanks @tengqm