[Pulsar Client Tools]Support generate documentation of pulsar admin cli automatically

[tuteng]

Motivation

Currently, the commands on the page http://pulsar.apache.org/docs/en/pulsar-admin/ are all manually added. when the document changes, there are often wrong contents. in order to solve this problem, we expect the commands on this page to be automatically generated. this pr is the first step. If it passes, we will add a new page on the website to show the automatically generated commands later.

Modifications

• Add a hidden command --generate-doc to automatically generate command line documents
• Add integration tests

Usage

./bin/pulsar-admin --generate-doc tenants
./bin/pulsar-admin --generate-doc namespaces
.....

The following is what we expect:

Verifying this change

Integration test pass

[sijie]

@tuteng

Great contribution to automate the documentation generation for admin CLI!

I have one suggestion to current change.

I don't think it is a good idea to add another flag --generate-doc in existing commands. Ideally the doc generator should be done in a separate tool. because you anyway create a PulsarAdminTool in the generateDocument method.

A better approach would be:

1. create a separate tool for generating documentation.
2. move generateDocument to the new tool.
3. in generateDocument, you can get all the commands from commandMap.
4. looping through the commands in commandMap and generate documentation for each command.

In this way, you don't change any existing commands and you are able to capture all the commands in the command map.

[sijie]

You can move the logic below into a method called generateDocument(JCommander command). Then you can iterate over the commands to generate the documentation for all the commands.

for (JCommander obj : jcommander.getCommands().values()) {
    generateDocument(obj);
}

[sijie]

when a user is generating documentation, he/she should NOT be required to create a Pulsar admin. So we should provide a mock implementation of adminFactory to return a mock implementation of PulsarAdmin.

[sijie]

removed the milestone for now. If we can make it before releasing 2.5.0, we can mark it for 2.5.0.

[tuteng]

Thank you for your suggestion. The situation you mentioned is my initial implementation plan. However, when I tested it, I found that different command objects jcommand was used in the PulsarAdminTool and CmdBase.

PulsarAdminTool:
https://github.com/apache/pulsar/blob/master/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/PulsarAdminTool.java#L87
CmdBase:
https://github.com/apache/pulsar/blob/master/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdBase.java#L38

All the child commands were inherited from the class CmdBase. In subclasses such as CmdTopics, we cannot get the commandMap object. Therefore, it may be necessary to pass down the commandmap object and the jcommand object of PulsarAdminTool. therefore, it is necessary to add some logic to the PulsarAdmintool. I am not sure if my understanding is correct. I hope to get your reply, but I will try this implementation as much as possible.

@sijie

[sijie]

I found that different command objects jcommand was used in the PulsarAdminTool and CmdBase.

The jcommand in PulsarrAdminTool is the root command.The jcommand in CmdBase is for a command group.

All the child commands were inherited from the class CmdBase. In subclasses such as CmdTopics, we cannot get the commandMap object.

You can get the command groups from the commandMap of PulsarAdminTool. Then you can iterate the command group. For each command group, you can get its sub commandMap.

[tuteng]

run java8 tests

[tuteng]

run integration tests

[tuteng]

run java8 tests

[sijie]

@sijie PTAL