feat(docs): Include Description and UsageText in docs output (#1287)
Include Description as part of the DESCRIPTION section, and put UsageText (if it is non-zero) into the Usage subsection.
This commit is contained in:
parent
b5d4a04c7f
commit
6373f5bf65
14
docs_test.go
14
docs_test.go
@ -110,6 +110,7 @@ Should be a part of the same code block
|
||||
}},
|
||||
}}
|
||||
app.UsageText = "app [first_arg] [second_arg]"
|
||||
app.Description = `Description of the application.`
|
||||
app.Usage = "Some app"
|
||||
app.Authors = []*Author{
|
||||
{Name: "Harrison", Email: "harrison@lolwut.com"},
|
||||
@ -178,6 +179,19 @@ func TestToMarkdownNoAuthors(t *testing.T) {
|
||||
expectFileContent(t, "testdata/expected-doc-no-authors.md", res)
|
||||
}
|
||||
|
||||
func TestToMarkdownNoUsageText(t *testing.T) {
|
||||
// Given
|
||||
app := testApp()
|
||||
app.UsageText = ""
|
||||
|
||||
// When
|
||||
res, err := app.ToMarkdown()
|
||||
|
||||
// Then
|
||||
expect(t, err, nil)
|
||||
expectFileContent(t, "testdata/expected-doc-no-usagetext.md", res)
|
||||
}
|
||||
|
||||
func TestToMan(t *testing.T) {
|
||||
// Given
|
||||
app := testApp()
|
||||
|
10
template.go
10
template.go
@ -86,16 +86,18 @@ var MarkdownDocTemplate = `% {{ .App.Name }} {{ .SectionNum }}
|
||||
{{ if .SynopsisArgs }}
|
||||
` + "```" + `
|
||||
{{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}` + "```" + `
|
||||
{{ end }}{{ if .App.UsageText }}
|
||||
{{ end }}{{ if .App.Description }}
|
||||
# DESCRIPTION
|
||||
|
||||
{{ .App.UsageText }}
|
||||
{{ .App.Description }}
|
||||
{{ end }}
|
||||
**Usage**:
|
||||
|
||||
` + "```" + `
|
||||
` + "```" + `{{ if .App.UsageText }}
|
||||
{{ .App.UsageText }}
|
||||
{{ else }}
|
||||
{{ .App.Name }} [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
` + "```" + `
|
||||
{{ end }}` + "```" + `
|
||||
{{ if .GlobalArgs }}
|
||||
# GLOBAL OPTIONS
|
||||
{{ range $v := .GlobalArgs }}
|
||||
|
4
testdata/expected-doc-full.man
vendored
4
testdata/expected-doc-full.man
vendored
@ -24,7 +24,7 @@ greet
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
app [first\_arg] [second\_arg]
|
||||
Description of the application.
|
||||
|
||||
.PP
|
||||
\fBUsage\fP:
|
||||
@ -33,7 +33,7 @@ app [first\_arg] [second\_arg]
|
||||
.RS
|
||||
|
||||
.nf
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
app [first\_arg] [second\_arg]
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
4
testdata/expected-doc-full.md
vendored
4
testdata/expected-doc-full.md
vendored
@ -16,12 +16,12 @@ greet
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
app [first_arg] [second_arg]
|
||||
Description of the application.
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
app [first_arg] [second_arg]
|
||||
```
|
||||
|
||||
# GLOBAL OPTIONS
|
||||
|
4
testdata/expected-doc-no-authors.md
vendored
4
testdata/expected-doc-no-authors.md
vendored
@ -16,12 +16,12 @@ greet
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
app [first_arg] [second_arg]
|
||||
Description of the application.
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
app [first_arg] [second_arg]
|
||||
```
|
||||
|
||||
# GLOBAL OPTIONS
|
||||
|
4
testdata/expected-doc-no-commands.md
vendored
4
testdata/expected-doc-no-commands.md
vendored
@ -16,12 +16,12 @@ greet
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
app [first_arg] [second_arg]
|
||||
Description of the application.
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
app [first_arg] [second_arg]
|
||||
```
|
||||
|
||||
# GLOBAL OPTIONS
|
||||
|
4
testdata/expected-doc-no-flags.md
vendored
4
testdata/expected-doc-no-flags.md
vendored
@ -10,12 +10,12 @@ greet
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
app [first_arg] [second_arg]
|
||||
Description of the application.
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
app [first_arg] [second_arg]
|
||||
```
|
||||
|
||||
# COMMANDS
|
||||
|
86
testdata/expected-doc-no-usagetext.md
vendored
Normal file
86
testdata/expected-doc-no-usagetext.md
vendored
Normal file
@ -0,0 +1,86 @@
|
||||
% greet 8
|
||||
|
||||
# NAME
|
||||
|
||||
greet - Some app
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
greet
|
||||
|
||||
```
|
||||
[--another-flag|-b]
|
||||
[--flag|--fl|-f]=[value]
|
||||
[--socket|-s]=[value]
|
||||
```
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
Description of the application.
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
```
|
||||
|
||||
# GLOBAL OPTIONS
|
||||
|
||||
**--another-flag, -b**: another usage text
|
||||
|
||||
**--flag, --fl, -f**="":
|
||||
|
||||
**--socket, -s**="": some 'usage' text (default: value)
|
||||
|
||||
|
||||
# COMMANDS
|
||||
|
||||
## config, c
|
||||
|
||||
another usage test
|
||||
|
||||
**--another-flag, -b**: another usage text
|
||||
|
||||
**--flag, --fl, -f**="":
|
||||
|
||||
### sub-config, s, ss
|
||||
|
||||
another usage test
|
||||
|
||||
**--sub-command-flag, -s**: some usage text
|
||||
|
||||
**--sub-flag, --sub-fl, -s**="":
|
||||
|
||||
## info, i, in
|
||||
|
||||
retrieve generic information
|
||||
|
||||
## some-command
|
||||
|
||||
|
||||
## usage, u
|
||||
|
||||
standard usage text
|
||||
|
||||
Usage for the usage text
|
||||
- formatted: Based on the specified ConfigMap and summon secrets.yml
|
||||
- list: Inspect the environment for a specific process running on a Pod
|
||||
- for_effect: Compare 'namespace' environment with 'local'
|
||||
|
||||
```
|
||||
func() { ... }
|
||||
```
|
||||
|
||||
Should be a part of the same code block
|
||||
|
||||
**--another-flag, -b**: another usage text
|
||||
|
||||
**--flag, --fl, -f**="":
|
||||
|
||||
### sub-usage, su
|
||||
|
||||
standard usage text
|
||||
|
||||
>Single line of UsageText
|
||||
|
||||
**--sub-command-flag, -s**: some usage text
|
Loading…
Reference in New Issue
Block a user