Fixing kubectl generated docs links

[tfogo]

I've been looking into fixing the broken links on this page that have been mentioned in a few issues.

Looks like the cause of this is that update-imported-docs/reference.yml doesn't import all the files generated from hack/generate-docs.sh in k/k. So one possible fix is just adding those files to reference.yml.

However, all of that information is also generated and imported by https://github.com/kubernetes-incubator/reference-docs and is available here: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands

We probably don't want to kubectl docs duplicated like that. Should we just replace the https://kubernetes.io/docs/reference/kubectl/kubectl/ page with a static md file that links to https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands? Or totally replace that page?

Would love to hear your thoughts/suggestions for the best way to fix this.

[zacharysarah]

@tfogo

We probably don't want to duplicate kubectl docs like that.

Agreed. 💯

Should we just replace the https://kubernetes.io/docs/reference/kubectl/kubectl/ page with a static md file that links to https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands?

It looks like /docs/reference/kubectl/kubectl/ is already a static MD file, and I agree it makes sense to keep it that way. We could replace the list of individual commands on that page with a link to https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands, which seems more likely to stay updated on an ongoing basis. Maybe add a link to the cheat sheet, too.

Totally out of scope: I'm annoyed that Hugo doesn't let us link directly to external URLs from the TOC, and requires us instead to have /docs/reference/kubectl/kubectl-cmds/.

@steveperry-53 @chenopis @Bradamant3 @zparnold 👋 What do you think?

[tfogo]

Thanks for your input @zacharysarah!

My understanding is that /docs/reference/kubectl/kubectl/ is generated from cobra using k/k/hack/generate-docs.sh and imported using this script. Following Generating Reference Pages for Kubernetes Components and Tools would overwrite /docs/reference/kubectl/kubectl/.

I just want to make sure we're on the same page that this change would require removing it from the doc generation process (specifically by removing these lines here: https://github.com/kubernetes/website/blob/master/update-imported-docs/reference.yml#L19-L20)

@steveperry-53 I'm particularly interested in your thoughts since I found a discussion on the mailing list where you suggested something else: https://groups.google.com/forum/#!topic/kubernetes-sig-docs/ZMVVNBu2TD8

[tengqm]

A related effort can be found at #9081 . The reference docs are generated using kubernetes-incubator/reference-docs. When compared this to the docs generated using k/k/hack/generate-docs.sh, we have a nice table view to show the command options. The script is outdated. We need to fix it.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.