generate man pages for kuma components

[tharun208]

generate man pages for kuma components

Signed-off-by: Tharun rajendrantharun@live.com

Testing

• Unit tests
• E2E tests
• Manual testing on Universal
• Manual testing on Kubernetes

[jpeach]

A few questions ....

• What's the use case for this? Would users run kumactl genman | man -l - (note, I had to google that!)? Or would you want to install this as part of a distribution package?
• Why only kubectl and not all the commands?
• Would an online reference help?

[tharun208]

A few questions ....

• What's the use case for this? Would users run kumactl genman | man -l - (note, I had to google that!)? Or would you want to install this as part of a distribution package?
• Why only kubectl and not all the commands?
• Would an online reference help?

1. Yes, we can add this to be installed as a part of the homebrew kumactl formulae script.
2. Because kumactl is the only part of homebrew ( maybe we can update the genman command for all kuma components, but generating man pages while installing will be only done for kumactl through the brew formulae script).
3. The man pages that are generated are not a single file and I think it is not a good idea to keep it on the website.

Need your thoughts for the online reference @jpeach @nickolaev

[jpeach]

@tharun208 I chatted about this with @bartsmykla and we have 3 kinds of documentation that we want to generate:

• protobuf API docs
• markdown CLI usage docs
• kumactl man pages

We propose that we add a consistent set of makefile targets for generating these, rather than building them into the CLI itself. So you would do

$ DESTDIR=/usr/local/man/man1 make docs/install/man
$ DESTDIR=/usr/share/doc/kuma/proto make docs/install/proto
$ DESTDIR=/usr/share/doc/kuma/cli make docs/install/markdown

Does that meet your needs?

[tharun208]

@tharun208 I chatted about this with @bartsmykla and we have 3 kinds of documentation that we want to generate:

• protobuf API docs
• markdown CLI usage docs
• kumactl man pages

We propose that we add a consistent set of makefile targets for generating these, rather than building them into the CLI itself. So you would do

$ DESTDIR=/usr/local/man/man1 make docs/install/man
$ DESTDIR=/usr/share/doc/kuma/proto make docs/install/proto
$ DESTDIR=/usr/share/doc/kuma/cli make docs/install/markdown

Does that meet your needs?

sounds good. But, I am a bit confused about man pages for kumactl. Is there a way to achieve this using the bash script?.
I think the only and easy way to generate it by using the cobra package inbuilt functions.

[jpeach]

@tharun208 I chatted about this with @bartsmykla and we have 3 kinds of documentation that we want to generate:

• protobuf API docs
• markdown CLI usage docs
• kumactl man pages

We propose that we add a consistent set of makefile targets for generating these, rather than building them into the CLI itself. So you would do

$ DESTDIR=/usr/local/man/man1 make docs/install/man
$ DESTDIR=/usr/share/doc/kuma/proto make docs/install/proto
$ DESTDIR=/usr/share/doc/kuma/cli make docs/install/markdown

Does that meet your needs?

sounds good. But, I am a bit confused about man pages for kumactl. Is there a way to achieve this using the bash script?.
I think the only and easy way to generate it by using the cobra package inbuilt functions.

yeh, you can just write the wrapper in ./tools/docs/manpages.go and then go run that from the build.

[tharun208]

@tharun208 I chatted about this with @bartsmykla and we have 3 kinds of documentation that we want to generate:

• protobuf API docs
• markdown CLI usage docs
• kumactl man pages

We propose that we add a consistent set of makefile targets for generating these, rather than building them into the CLI itself. So you would do

$ DESTDIR=/usr/local/man/man1 make docs/install/man
$ DESTDIR=/usr/share/doc/kuma/proto make docs/install/proto
$ DESTDIR=/usr/share/doc/kuma/cli make docs/install/markdown

Does that meet your needs?

sounds good. But, I am a bit confused about man pages for kumactl. Is there a way to achieve this using the bash script?.
I think the only and easy way to generate it by using the cobra package inbuilt functions.

yeh, you can just write the wrapper in ./tools/docs/manpages.go and then go run that from the build.

sure, then can we do all the three documentation implementations in the same pr?

[tharun208]

@jpeach, do we need the generated man pages also to be part of the codebase?

[jpeach]

@jpeach, do we need the generated man pages also to be part of the codebase?

I don't know of any reason to want that, do you?

[tharun208]

@jpeach, do we need the generated man pages also to be part of the codebase?

I don't know of any reason to want that, do you?

no

[jpeach]

Looking at the generated output, the .TH element is all wrong. The format is documented here, so it ought to be something like this:

.nh
.TH kuma\-cp 1 2021-06-01 Kuma "Kuma Manual"

but it gets generated like this:

.nh
.TH kuma\-cp(1)Jun 2021
Auto generated by spf13/cobra

Looks like this is spf13/cobra#1049

[jpeach]

Once #2196 lands, could you please rebase? Thanks!

[jpeach]

This looks great. I'm going to land this without waiting for the cobra upgrade, because that is stuck behind some integration test failures.