Fix usage and hyperlinks in kubectl reference

[brianpursley]

Fixes command usage missing kubectl
Fixes subcommand usage missing kubectl <maincommand>
Fixes problem with hyperlinks surrounded by [ ] not displaying correctly...
Fixes kubernetes/website#18444

[brianpursley]

Generating a preview now...

[brianpursley]

Here is a kubectl reference docs preview generated using the code in this PR:

https://deploy-preview-19864--kubernetes-io-master-staging.netlify.com/docs/reference/generated/kubectl/kubectl-commands

[brianpursley]

/assign @steveperry-53

[brianpursley]

/cc @kbhawkey

[tengqm]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: brianpursley, tengqm

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [tengqm]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[kbhawkey]

👀

[kbhawkey]

Previously:

[<a href="http://golang.org/pkg/text/template/#pkg-overview]">http://golang.org/pkg/text/template/#pkg-overview]</a>. </td>

Now (from generated sample (https://deploy-preview-19864--kubernetes-io-master-staging.netlify.com/docs/reference/generated/kubectl/kubectl-commands#-em-poddisruptionbudget-em-):

<td>Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates <span>[</span><a href="http://golang.org/pkg/text/template/#pkg-overview">http://golang.org/pkg/text/template/#pkg-overview</a><span>]</span>. </td>
</tr>

[brianpursley]

It just wraps the square brackets in spans, so they don't get merged into the hyperlink url. Probably only needed to do that for the closing square bracket but wanted to be consistent.

Do you think that will cause a problem for it to render that way?

[brianpursley]

By the way this should remove the need to do the manual fix that used to have the be performed every time.

[kbhawkey]

I understand. What happened to the middle ] bracket in the original ref?

[brianpursley]

The middle ], the one that got attached to #pkg-overview] is gone... it wasn't supposed to be part of the URL.

The problem was that having ] directly after the URL, with no spaces, was messing up the markdown processor, and it was considering it to be part of the URL.

The problem arises because kubectl's cobra command is not trying to generate markdown, but the reference-docs generator is taking the output from kubectl and running it through a markdown processor and some things like [ ] are being interpreted as markdown's URL syntax when really it should be treated more like parentheses.

There isn't a great way to escape ] in markdown, so a solution (the one I chose in this PR) is to wrap it with so that markdown won't try to interpret it as a symbol to be processed.

For reference, if you run kubectl apply --help here is the part where this shows up:

--template='': Template string or path to template file to use when -o=go-template, -o=go-template-file. The
template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].

But again, this is in the command-line output, which is not markdown, so it displays fine in the command line because there is no markdown processor to mess it up.

I hope that I have understood and answered your question. Let me know if I haven't.

[kbhawkey]

Thanks @brianpursley . I wanted to know what happened to the extra ] and assumed that the parser no longer generated this character because of the new formatting. Your solution works around the problem. Ideally, the kubectl text formatting corrections could be made in the upstream code. There are a number of fixes in this code for formatting issues.
/lgtm