From 2cb62f5091a7a7e304003b4a9134c66bb016fc08 Mon Sep 17 00:00:00 2001 From: Sascha Grunert Date: Thu, 19 Sep 2019 14:29:06 +0200 Subject: [PATCH] Improve docs generation for cli.Authors This allows specifying multiple authors, whereas no available authors will be formatted correctly now. Signed-off-by: Sascha Grunert --- .gitignore | 3 +- docs_test.go | 18 +++++++- template.go | 7 ++-- testdata/expected-doc-full.man | 7 +++- testdata/expected-doc-full.md | 5 ++- testdata/expected-doc-no-authors.md | 61 ++++++++++++++++++++++++++++ testdata/expected-doc-no-commands.md | 5 ++- testdata/expected-doc-no-flags.md | 5 ++- 8 files changed, 97 insertions(+), 14 deletions(-) create mode 100644 testdata/expected-doc-no-authors.md diff --git a/.gitignore b/.gitignore index 7a7e2d9ef0..501b8e88ac 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ *.coverprofile +*.orig node_modules/ -vendor \ No newline at end of file +vendor diff --git a/docs_test.go b/docs_test.go index e685f90950..e52cf8bd31 100644 --- a/docs_test.go +++ b/docs_test.go @@ -64,7 +64,10 @@ func testApp() *App { }} app.UsageText = "app [first_arg] [second_arg]" app.Usage = "Some app" - app.Authors = []*Author{{Name: "Harrison", Email: "harrison@lolwut.com"}} + app.Authors = []*Author{ + {Name: "Harrison", Email: "harrison@lolwut.com"}, + {Name: "Oliver Allen", Email: "oliver@toyshop.com"}, + } return app } @@ -112,6 +115,19 @@ func TestToMarkdownNoCommands(t *testing.T) { expectFileContent(t, "testdata/expected-doc-no-commands.md", res) } +func TestToMarkdownNoAuthors(t *testing.T) { + // Given + app := testApp() + app.Authors = []*Author{} + + // When + res, err := app.ToMarkdown() + + // Then + expect(t, err, nil) + expectFileContent(t, "testdata/expected-doc-no-authors.md", res) +} + func TestToMan(t *testing.T) { // Given app := testApp() diff --git a/template.go b/template.go index 78e182f5c4..1cc4bd624b 100644 --- a/template.go +++ b/template.go @@ -71,10 +71,9 @@ OPTIONS: {{end}}{{end}} ` -var MarkdownDocTemplate = `% {{ .App.Name }}(8) {{ .App.Description }} -{{ range $Author := .App.Authors}} -% {{ $Author.Name }} -{{- end}} +var MarkdownDocTemplate = `% {{ .App.Name }}(8){{ if .App.Description }} {{ .App.Description }}{{ end }} +{{ range $a := .App.Authors }} +% {{ $a }}{{ end }} # NAME diff --git a/testdata/expected-doc-full.man b/testdata/expected-doc-full.man index 5190698fa3..f28f4c78b3 100644 --- a/testdata/expected-doc-full.man +++ b/testdata/expected-doc-full.man @@ -1,7 +1,10 @@ .nh -.TH greet(8) +.TH greet(8) -.SH Harrison +.SH Harrison harrison@lolwut.com +\[la]mailto:harrison@lolwut.com\[ra] +Oliver Allen oliver@toyshop.com +\[la]mailto:oliver@toyshop.com\[ra] .SH NAME .PP diff --git a/testdata/expected-doc-full.md b/testdata/expected-doc-full.md index 23d7c23745..5bfb01ed46 100644 --- a/testdata/expected-doc-full.md +++ b/testdata/expected-doc-full.md @@ -1,6 +1,7 @@ -% greet(8) +% greet(8) -% Harrison +% Harrison +% Oliver Allen # NAME diff --git a/testdata/expected-doc-no-authors.md b/testdata/expected-doc-no-authors.md new file mode 100644 index 0000000000..a49481a4f8 --- /dev/null +++ b/testdata/expected-doc-no-authors.md @@ -0,0 +1,61 @@ +% greet(8) + + +# NAME + +greet - Some app + +# SYNOPSIS + +greet + +``` +[--another-flag|-b] +[--flag|--fl|-f]=[value] +[--socket|-s]=[value] +``` + +# DESCRIPTION + +app [first_arg] [second_arg] + +**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 + + diff --git a/testdata/expected-doc-no-commands.md b/testdata/expected-doc-no-commands.md index 18d8e357e8..f82f642a0b 100644 --- a/testdata/expected-doc-no-commands.md +++ b/testdata/expected-doc-no-commands.md @@ -1,6 +1,7 @@ -% greet(8) +% greet(8) -% Harrison +% Harrison +% Oliver Allen # NAME diff --git a/testdata/expected-doc-no-flags.md b/testdata/expected-doc-no-flags.md index 8ce60fd7ad..c32a9fccee 100644 --- a/testdata/expected-doc-no-flags.md +++ b/testdata/expected-doc-no-flags.md @@ -1,6 +1,7 @@ -% greet(8) +% greet(8) -% Harrison +% Harrison +% Oliver Allen # NAME