Generate CLI Documentation from Go code #294
Conversation
|
|
||
| return cmd | ||
| } | ||
|
|
||
| // Custom template for TOP to fix the namespace usage statement (default template shows parent usage). |
There was a problem hiding this comment.
The reason top and upgrade had custom templates was because they have flags that override parent flags, and the default usage statements would show the parent usage for those flags, instead of the child usage of those flags.
There was a problem hiding this comment.
From what I saw, the overriden flags were being printed out in the default usage statement, and not the parent usage. Adding the flag explicitly in the template was leading to the overriden flags being printed twice.
|
|
||
| // generates a markdown file for each CLI command | ||
| _, b, _, _ := runtime.Caller(0) | ||
| docsPath := filepath.Join(filepath.Dir(b), "../../docs/content/reference") |
There was a problem hiding this comment.
I would rather have the CLI spit out all of this to stdout, and then the caller of the generator can pipe that output into our docs file. I don't want our CLI itself to write the file.
| ) | ||
|
|
||
| var ( | ||
| pkgName = "nginx-meshctl" | ||
| version = "0.0.0" | ||
| commit = "local" | ||
| genDocs = "" |
There was a problem hiding this comment.
Rather than a variable built in, how about a flag that a user specifies, such as --verbose-usage or something along those lines?
Proposed changes
make generaterule which autogenerates the documentation.go run -ldflags '-X main.genDocs=true' cmd/nginx-meshctl/main.go > /dev/nullto just generate the documentation.top.goandupgrade.gosince they were printing out some flags redundantly.Checklist
Before creating a PR, run through this checklist and mark each as complete.