Issue #3104: Automatically Generate Document for Operator Executable #4112
Conversation
Documentation/operator.md
Outdated
| @@ -0,0 +1,46 @@ | |||
| Usage of Operator | |||
There was a problem hiding this comment.
| Usage of Operator | |
| Operator CLI Flags |
nit :)
There was a problem hiding this comment.
I think we also need the following at the top of the file so it can be included on website (similar to how API.md is included):
---
title: "Operator CLI Flags"
description: "Lists of possible arguments passed to operator executable."
lead: ""
date: 2021-06-18T08:49:31+00:00
draft: false
images: []
menu:
docs:
parent: "operator"
weight: 1000
toc: true
---
date can be static for now.
There was a problem hiding this comment.
modification done as instructed :)
cmd/po-docgen/operator.go
Outdated
| fmt.Printf("%d-%02d-%02dT%02d:%02d:%02d-00:00\n", | ||
| timeNow.Year(), timeNow.Month(), timeNow.Day(), | ||
| timeNow.Hour(), timeNow.Minute(), timeNow.Second()) |
There was a problem hiding this comment.
We cannot do a dynamic date as this will always fail in CI.
There was a problem hiding this comment.
ok, I will put date of today hardcoded.
|
/retest |
|
rebase to master branch, hope the previously failed E2E test will pass. |
cmd/po-docgen/operator.go
Outdated
|
|
||
| if exprCall.Fun.(*ast.SelectorExpr).X.(*ast.Ident).Name == "flagset" { | ||
| var argName, argDefaultValue, argDescription string | ||
| if exprCall.Fun.(*ast.SelectorExpr).Sel.Name == "StringVar" { |
There was a problem hiding this comment.
Shouldn't it fail hard if it encounters a flag type that isn't supported by the generator? Also a switch/case would be more idiomatic.
selectorExpr, ok := exprCall.Fun.(*ast.SelectorExpr)
if !ok {
continue
}
switch selectorExpr.Sel.Name {
case "StringVar":
...
default:
// return an error
}
cmd/po-docgen/operator.go
Outdated
|
|
||
| func resolveDurationExpr(expr ast.Expr) string { | ||
| var exprIdent *ast.Ident | ||
| exprSelector, ok := expr.(*ast.SelectorExpr) |
There was a problem hiding this comment.
it would be a nice place to use type switches.
There was a problem hiding this comment.
much simpler than c++ 😀
cmd/po-docgen/operator.go
Outdated
| return exprIdent.Name | ||
| } | ||
|
|
||
| return "No Identifier to Resolve" |
There was a problem hiding this comment.
shouldn't it return an error?
There was a problem hiding this comment.
agree, returning an error is better. anyone wants to add a new argument should also update the doc generator if needed.
cmd/po-docgen/operator.go
Outdated
|
|
||
| func resolveConstStringExpr(expr ast.Expr) string { | ||
|
|
||
| exprBasicLit, ok := expr.(*ast.BasicLit) |
There was a problem hiding this comment.
ditto about type switches.
po-docgen and Makefile are updated to automatically generate Document/operator.md from cmd/operator/main.go, by parsing the definition of flagset in the init() function.
There is a limitation that constants imported from other packages are not resolved into its final literal value, runtime string contatenation using fmt.Sprintf is not evaluated by the doc generator. However, constants in the same file is resolved and constant expressions such as string concatenation is evaluated.
Release Note Template (will be copied)