From 7d13bcb8a547a581323a34fd43a0df5c27de7fa3 Mon Sep 17 00:00:00 2001 From: Link Dupont Date: Wed, 30 Jun 2021 13:53:31 -0400 Subject: [PATCH] feat(docs): Include Description and UsageText in docs output Include Description as part of the DESCRIPTION section, and put UsageText (if it is non-zero) into the Usage subsection. --- docs_test.go | 14 +++++ template.go | 10 ++-- testdata/expected-doc-full.man | 4 +- testdata/expected-doc-full.md | 4 +- testdata/expected-doc-no-authors.md | 4 +- testdata/expected-doc-no-commands.md | 4 +- testdata/expected-doc-no-flags.md | 4 +- testdata/expected-doc-no-usagetext.md | 86 +++++++++++++++++++++++++++ 8 files changed, 116 insertions(+), 14 deletions(-) create mode 100644 testdata/expected-doc-no-usagetext.md diff --git a/docs_test.go b/docs_test.go index 962c366640..5308f372f7 100644 --- a/docs_test.go +++ b/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() diff --git a/template.go b/template.go index 69e040e7fb..708a402813 100644 --- a/template.go +++ b/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 }} diff --git a/testdata/expected-doc-full.man b/testdata/expected-doc-full.man index 3ac35539cb..3df4684a2d 100644 --- a/testdata/expected-doc-full.man +++ b/testdata/expected-doc-full.man @@ -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 diff --git a/testdata/expected-doc-full.md b/testdata/expected-doc-full.md index 7b8c0d7e9e..f3374e5b1c 100644 --- a/testdata/expected-doc-full.md +++ b/testdata/expected-doc-full.md @@ -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 diff --git a/testdata/expected-doc-no-authors.md b/testdata/expected-doc-no-authors.md index 7b8c0d7e9e..f3374e5b1c 100644 --- a/testdata/expected-doc-no-authors.md +++ b/testdata/expected-doc-no-authors.md @@ -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 diff --git a/testdata/expected-doc-no-commands.md b/testdata/expected-doc-no-commands.md index adaedb43e0..1c4fd075ed 100644 --- a/testdata/expected-doc-no-commands.md +++ b/testdata/expected-doc-no-commands.md @@ -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 diff --git a/testdata/expected-doc-no-flags.md b/testdata/expected-doc-no-flags.md index ebd0416ecd..cf766ad9ca 100644 --- a/testdata/expected-doc-no-flags.md +++ b/testdata/expected-doc-no-flags.md @@ -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 diff --git a/testdata/expected-doc-no-usagetext.md b/testdata/expected-doc-no-usagetext.md new file mode 100644 index 0000000000..da31b38ef1 --- /dev/null +++ b/testdata/expected-doc-no-usagetext.md @@ -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