Add documentation for minikube CLI commands

[blueelvis]

Fixes #4271

This is the first pass on documenting the options, commands and flags available in the minikube CLI.

I went ahead and added for all the commands and not only the start command as mentioned in the issue.

/assign tstromberg

[k8s-ci-robot]

Hi @blueelvis. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: blueelvis
To complete the pull request process, please assign ra489
You can assign the PR to them by writing /assign @ra489 in a comment when ready.

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

Needs approval from an approver in each of these files:

• OWNERS

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

[minikube-bot]

Can one of the admins verify this patch?

[afbjorklund]

These are very likely to get out of date, due to the duplication of information...

Could we use something automated, similar to help2man, to generate it ?

[RA489]

@minikube-bot OK to test

[tstromberg]

Thanks for this PR!

I do agree with afbjorklund@ - these docs are great right now, but will get stale very fast. The command-line framework we are using, Cobra, allows automatic generation of markdown docs.

https://github.com/spf13/cobra/blob/master/doc/md_docs.md

By auto-generating docs, we can guarantee that users who are using --help get the same rich help as those using our doc website. Here's an example using Cobra's VisitAll() that we could emulate - though my preference would be that each command gets it's own markdown file:

https://github.com/GoogleContainerTools/skaffold/blob/68fe5670b38a19cc5f689040ad2088c5bdeea779/cmd/skaffold/man/man.go#L38

[RA489]

@minikube-bot OK to test

[blueelvis]

@afbjorklund @tstromberg - Agreed. Let me try using Cobra's auto generation and get back.

[tstromberg]

I thought about this some more: we should not let perfect be the enemy of good, particularly when it comes to documentation. If Cobra auto-generation turns out to be difficult, I would be rather accept this doc as is, and replace it with automation as soon as possible. Let me know how your experiment goes.

Thank you!

[blueelvis]

@tstromberg @afbjorklund - This looks really promising. I generated the attached (start.txt) markdown file for the start command. After a couple of tweaks, it could look really good!

The cobra.Command accepts a lot of parameters which can be filled with Examples and other documentation! That would flesh out the documentation automatically.

Let me know if you are open to merge this PR now and I can work on another one meanwhile to integrate this with all of our commands and have something automated?

[RA489]

@minikube-bot OK to test

[blueelvis]

ping @tstromberg

[tstromberg]

Happy to merge this one now while we work out how to automate it. Thank you for writing this up!