Rendering issues in command line documentation

[craigbox]

Modify https://github.com/istio/pkg/blob/master/collateral/control.go to fix rendering issues in command line output on istio.io.

Command output

For example: https://istio.io/latest/docs/reference/commands/istioctl/#istioctl-completion-bash

It seems that these are all the command output help. For example:

$ istioctl completion bash -h
Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

    source <(istioctl completion bash)

To load completions for every new session, execute once:

#### Linux:

    istioctl completion bash > /etc/bash_completion.d/istioctl

#### macOS:

    istioctl completion bash > $(brew --prefix)/etc/bash_completion.d/istioctl

You will need to start a new shell for this setup to take effect.

Usage:
  istioctl completion bash

Bad text

Please use with caution as these environment variables are experimental and can change anytime.

That shouldn't be true any more.

Bad nesting

Currently appears like this:

I think it would make more sense to appear like this:

[peterj]

The markdown in the docs is coming from the completion command we're importing from cobra: https://github.com/spf13/cobra/blob/371ae25d2c82e519feb48c82d142e6a696fd06dd/completions.go#L734

[wasup-yash]

This issue will be resolved as #15451 and #52274 in istio/istio get merged right?

[peterj]

Yes, you're right.

[wasup-yash]

Yes, you're right.

just asking, if I can review the pr's that I understand and ask questions about some of them (for the ones that I don't understand) on pr or Slack ig ? (I know my review don't help in merge though XD)

[peterj]

of course, feel free!

[craigbox]

@wasup-yash If you're getting involved because you're interested in the LFX program, then I would encourage you to learn how these changes are going to make their way into the Istio documentation: both https://istio.io/latest/docs/reference/commands/istioctl/ and https://preliminary.istio.io/latest/docs/reference/commands/istioctl/ for example.

[wasup-yash]

@wasup-yash If you're getting involved because you're interested in the LFX program, then I would encourage you to learn how these changes are going to make their way into the Istio documentation: both https://istio.io/latest/docs/reference/commands/istioctl/ and https://preliminary.istio.io/latest/docs/reference/commands/istioctl/ for example.

Thanks a lot for the reply, I am not getting involved due to the LFX program as I am already an LFX graduated mentee, I was just trying to understand more about service meshes, and the best I know is Istio to get started , Although I will surely check out the resources that you mentioned

[craigbox]

Cherry-pick to release-1.23 awaiting RMs in https://github.com/istio/istio/pull/52430.

[craigbox]

Looks good in https://preliminary.istio.io/latest/docs/reference/commands/istioctl/ !