From 9569de9a08ce54c40f2b1f54e714978c36b65917 Mon Sep 17 00:00:00 2001 From: Guillaume Fouillet Date: Mon, 8 Jul 2024 12:21:13 +0200 Subject: [PATCH 1/3] fix(documentation): incorrect generation of flag description This commit fix the generation of flag description when there is a shortname for a flag. - Before this commit, the shortname would be prefixed by two dash (ex `--o`), which display an incorrect documentation (ex: "`--o`, `--output` | (...)" ). - After the commit, flags with a name with a lenght of 1 will be displayed with a single dash, according to shell command usual behavior. --- documentation.go | 14 +++++++++----- documentation_test.go | 30 ++++++++++++++++++++++-------- 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/documentation.go b/documentation.go index 1d495014..dec71204 100644 --- a/documentation.go +++ b/documentation.go @@ -26,7 +26,7 @@ This command generates a markdown formatted document with all the commands, thei ` var documentationExamples = ` - juju documentation + juju documentation juju documentation --split juju documentation --split --no-index --out /tmp/docs @@ -493,14 +493,18 @@ func (d *documentationCommand) formatFlags(c Command, info *Info) string { formatted := "| Flag | Default | Usage |\n" formatted += "| --- | --- | --- |\n" for _, fs := range byName { - theFlags := "" + formattedFlags := "" for i, f := range fs { if i > 0 { - theFlags += ", " + formattedFlags += ", " + } + if len(f.Name) == 1 { + formattedFlags += fmt.Sprintf("`-%s`", f.Name) + } else { + formattedFlags += fmt.Sprintf("`--%s`", f.Name) } - theFlags += fmt.Sprintf("`--%s`", f.Name) } - formatted += fmt.Sprintf("| %s | %s | %s |\n", theFlags, + formatted += fmt.Sprintf("| %s | %s | %s |\n", formattedFlags, EscapeMarkdown(fs[0].DefValue), strings.ReplaceAll(EscapeMarkdown(fs[0].Usage), "\n", " "), ) diff --git a/documentation_test.go b/documentation_test.go index feb4e606..f04f0274 100644 --- a/documentation_test.go +++ b/documentation_test.go @@ -30,7 +30,7 @@ func (s *documentationSuite) TestFormatCommand(c *gc.C) { SeeAlso: []string{"clouds", "update-cloud", "remove-cloud", "update-credential"}, Aliases: []string{"cloud-add", "import-cloud"}, }, - flags: []string{"force", "format", "output"}, + flags: []testFlag{{name: "force", short: "f"}, {name: "format" /* no short flag */}, {name: "output", short: "o"}}, }, title: false, expected: (` @@ -45,9 +45,9 @@ summary for add-cloud... ### Options | Flag | Default | Usage | | --- | --- | --- | -| ` + "`" + `--force` + "`" + ` | default value for "force" flag | description for "force" flag | +| ` + "`" + `-f` + "`" + `, ` + "`" + `--force` + "`" + ` | default value for "force" flag | description for "force" flag | | ` + "`" + `--format` + "`" + ` | default value for "format" flag | description for "format" flag | -| ` + "`" + `--output` + "`" + ` | default value for "output" flag | description for "output" flag | +| ` + "`" + `-o` + "`" + `, ` + "`" + `--output` + "`" + ` | default value for "output" flag | description for "output" flag | ## Examples examples for add-cloud... @@ -68,7 +68,7 @@ details for add-cloud... Doc: "insert details here...", Examples: "insert examples here...", }, - flags: []string{}, + flags: []testFlag{}, }, title: false, expected: (` @@ -105,7 +105,13 @@ insert details here... // documentation output. type docTestCommand struct { info *cmd.Info - flags []string + flags []testFlag +} + +// testFlag is a definition for flag in test. It allows to provide an optional short name for the flag +type testFlag struct { + name string + short string // optional } func (c *docTestCommand) Info() *cmd.Info { @@ -114,9 +120,17 @@ func (c *docTestCommand) Info() *cmd.Info { func (c *docTestCommand) SetFlags(f *gnuflag.FlagSet) { for _, flag := range c.flags { - f.String(flag, - fmt.Sprintf("default value for %q flag", flag), - fmt.Sprintf("description for %q flag", flag)) + var fakeValue string + defaultValue := fmt.Sprintf("default value for %q flag", flag.name) + description := fmt.Sprintf("description for %q flag", flag.name) + f.StringVar(&fakeValue, flag.name, + defaultValue, + description) + if flag.short != "" { + f.StringVar(&fakeValue, flag.short, + defaultValue, + description) + } } } From b21531c88b038a8d695d161e398dbca1b65ca14e Mon Sep 17 00:00:00 2001 From: Guillaume Fouillet Date: Mon, 15 Jul 2024 09:05:44 +0200 Subject: [PATCH 2/3] fix(documentation): adjust doc indentation for `juju documentation` Before, there were excessive indentation spaces for examples of the command `juju documentation`. After the commit, the indentation spaces are trimmed for a cleaner and more structured rendering of the example for the command. --- documentation.go | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/documentation.go b/documentation.go index dec71204..6d4c27a3 100644 --- a/documentation.go +++ b/documentation.go @@ -26,27 +26,27 @@ This command generates a markdown formatted document with all the commands, thei ` var documentationExamples = ` - juju documentation - juju documentation --split - juju documentation --split --no-index --out /tmp/docs - - To render markdown documentation using a list of existing - commands, you can use a file with the following syntax - - command1: id1 - command2: id2 - commandN: idN - - For example: - - add-cloud: 1183 - add-secret: 1284 - remove-cloud: 4344 - - Then, the urls will be populated using the ids indicated - in the file above. - - juju documentation --split --no-index --out /tmp/docs --discourse-ids /tmp/docs/myids + juju documentation + juju documentation --split + juju documentation --split --no-index --out /tmp/docs + +To render markdown documentation using a list of existing +commands, you can use a file with the following syntax + + command1: id1 + command2: id2 + commandN: idN + +For example: + + add-cloud: 1183 + add-secret: 1284 + remove-cloud: 4344 + +Then, the urls will be populated using the ids indicated +in the file above. + + juju documentation --split --no-index --out /tmp/docs --discourse-ids /tmp/docs/myids ` type documentationCommand struct { From 61f3dd32a8c1f0980faf1a7ac70b3818c424e559 Mon Sep 17 00:00:00 2001 From: Guillaume Fouillet Date: Mon, 15 Jul 2024 10:05:52 +0200 Subject: [PATCH 3/3] docs(documentation): add comments to flag formatting Before, flag formatting may be confusing in the code. After, some comments helps the reader to figure out what's going one. --- documentation.go | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/documentation.go b/documentation.go index 6d4c27a3..236c267d 100644 --- a/documentation.go +++ b/documentation.go @@ -473,7 +473,10 @@ func (d *documentationCommand) formatFlags(c Command, info *Info) string { c.SetFlags(f) } - // group together all flags for a given value + // group together all flags for a given value, meaning that flag which sets the same value are + // grouped together and displayed with the same description, as below: + // + // -s, --short, --alternate-string | default value | some description. flags := make(map[interface{}]flagsByLength) f.VisitAll(func(f *gnuflag.Flag) { flags[f.Value] = append(flags[f.Value], f) @@ -483,6 +486,9 @@ func (d *documentationCommand) formatFlags(c Command, info *Info) string { } // sort the output flags by shortest name for each group. + // Caution: this mean that description/default value displayed in documentation will + // be the one of the shortest alias. Other will be discarded. Be careful to have the same default + // values between each alias, and put the description on the shortest alias. var byName flagsByName for _, fl := range flags { sort.Sort(fl) @@ -493,6 +499,7 @@ func (d *documentationCommand) formatFlags(c Command, info *Info) string { formatted := "| Flag | Default | Usage |\n" formatted += "| --- | --- | --- |\n" for _, fs := range byName { + // Collect all flag aliases (usually a short one and a plain one, like -v / --verbose) formattedFlags := "" for i, f := range fs { if i > 0 { @@ -504,6 +511,8 @@ func (d *documentationCommand) formatFlags(c Command, info *Info) string { formattedFlags += fmt.Sprintf("`--%s`", f.Name) } } + // display all the flags aliases and the default value and description of the shortest one. + // Escape Markdown in description in order to display it cleanly in the final documentation. formatted += fmt.Sprintf("| %s | %s | %s |\n", formattedFlags, EscapeMarkdown(fs[0].DefValue), strings.ReplaceAll(EscapeMarkdown(fs[0].Usage), "\n", " "),