Skip to content

Commit

Permalink
Merge pull request #115 from juju/v3
Browse files Browse the repository at this point in the history
chore: Merge v3 to v4
  • Loading branch information
gfouillet authored Jul 17, 2024
2 parents 48cf985 + cc2574f commit 7b66a5b
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 33 deletions.
63 changes: 38 additions & 25 deletions documentation.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,26 +27,26 @@ 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 --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 {
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -493,14 +499,21 @@ func (d *documentationCommand) formatFlags(c Command, info *Info) string {
formatted := "| Flag | Default | Usage |\n"
formatted += "| --- | --- | --- |\n"
for _, fs := range byName {
theFlags := ""
// Collect all flag aliases (usually a short one and a plain one, like -v / --verbose)
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,
// 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", " "),
)
Expand Down
30 changes: 22 additions & 8 deletions documentation_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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: (`
Expand All @@ -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...
Expand All @@ -68,7 +68,7 @@ details for add-cloud...
Doc: "insert details here...",
Examples: "insert examples here...",
},
flags: []string{},
flags: []testFlag{},
},
title: false,
expected: (`
Expand Down Expand Up @@ -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 {
Expand All @@ -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)
}
}
}

Expand Down

0 comments on commit 7b66a5b

Please sign in to comment.