Implement review comments

Signed-off-by: Sascha Grunert <sgrunert@suse.com>

docs.go

@@ -7,7 +7,6 @@ import (
 	"sort"
 	"strings"
 	"text/template"
-	"time"
 
 	"github.com/cpuguy83/go-md2man/md2man"
 )
@@ -33,7 +32,7 @@ func (a *App) ToMan() (string, error) {
 	return string(man), nil
 }
 
-type CliTemplate struct {
+type cliTemplate struct {
 	App          *App
 	Date         string
 	Commands     []string
@@ -42,45 +41,41 @@ type CliTemplate struct {
 }
 
 func (a *App) writeDocTemplate(w io.Writer) error {
-	now := time.Now()
 	const name = "cli"
 	t, err := template.New(name).Parse(MarkdownDocTemplate)
 	if err != nil {
 		return err
 	}
-	return t.ExecuteTemplate(w, name, &CliTemplate{
+	return t.ExecuteTemplate(w, name, &cliTemplate{
 		App:          a,
-		Date:         fmt.Sprintf("%s %d", now.Month(), now.Year()),
 		Commands:     prepareCommands(a.Commands, 0),
 		GlobalArgs:   prepareArgsWithValues(a.Flags),
 		SynopsisArgs: prepareArgsSynopsis(a.Flags),
 	})
 }
 
 const nl = "\n"
-const noDescription = "_no description available_"
 
 func prepareCommands(commands []Command, level int) []string {
 	coms := []string{}
 	for i := range commands {
 		command := &commands[i]
-		prepared := strings.Repeat("#", level+2) + " " +
-			strings.Join(command.Names(), ", ") + nl
-
-		usage := noDescription
+		usage := ""
 		if command.Usage != "" {
 			usage = command.Usage
 		}
-		prepared += nl + usage + nl
+
+		prepared := fmt.Sprintf("%s %s\n\n%s\n",
+			strings.Repeat("#", level+2),
+			strings.Join(command.Names(), ", "),
+			usage,
+		)
 
 		flags := prepareArgsWithValues(command.Flags)
 		if len(flags) > 0 {
 			prepared += nl
 		}
 		prepared += strings.Join(flags, nl)
-		if len(flags) > 0 {
-			prepared += nl
-		}
 
 		coms = append(coms, prepared)
 
@@ -142,9 +137,6 @@ func prepareFlags(
 // flagDetails returns a string containing the flags metadata
 func flagDetails(flag Flag) string {
 	description := flag.GetUsage()
-	if flag.GetUsage() == "" {
-		description = noDescription
-	}
 	value := flag.GetValue()
 	if value != "" {
 		description += " (default: " + value + ")"

docs_test.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"io/ioutil"
 	"testing"
 )
 
@@ -57,26 +58,58 @@ func testApp() *App {
 	return app
 }
 
-func TestToMarkdown(t *testing.T) {
+func expectFileContent(t *testing.T, file, expected string) {
+	data, err := ioutil.ReadFile(file)
+	expect(t, err, nil)
+	expect(t, string(data), expected)
+}
+
+func TestToMarkdownFull(t *testing.T) {
+	// Given
+	app := testApp()
+
+	// When
+	res, err := app.ToMarkdown()
+
+	// Then
+	expect(t, err, nil)
+	expectFileContent(t, "testdata/expected-doc-full.md", res)
+}
+
+func TestToMarkdownNoFlags(t *testing.T) {
+	// Given
+	app := testApp()
+	app.Flags = nil
+
+	// When
+	res, err := app.ToMarkdown()
+
+	// Then
+	expect(t, err, nil)
+	expectFileContent(t, "testdata/expected-doc-no-flags.md", res)
+}
+
+func TestToMarkdownNoCommands(t *testing.T) {
 	// Given
 	app := testApp()
+	app.Commands = nil
 
 	// When
-	_, err := app.ToMarkdown()
+	res, err := app.ToMarkdown()
 
 	// Then
-	// TODO: extend test case
 	expect(t, err, nil)
+	expectFileContent(t, "testdata/expected-doc-no-commands.md", res)
 }
 
 func TestToMan(t *testing.T) {
 	// Given
 	app := testApp()
 
 	// When
-	_, err := app.ToMan()
+	res, err := app.ToMan()
 
 	// Then
-	// TODO: extend test case
 	expect(t, err, nil)
+	expectFileContent(t, "testdata/expected-doc-full.man", res)
 }

template.go

@@ -74,8 +74,8 @@ OPTIONS:
 `
 
 var MarkdownDocTemplate = `% {{ .App.Name }}(8) {{ .App.Description }}
+
 % {{ .App.Author }}
-% {{ .Date }}
 
 # NAME
 
@@ -85,9 +85,8 @@ var MarkdownDocTemplate = `% {{ .App.Name }}(8) {{ .App.Description }}
 
 {{ .App.Name }}
 {{ if .SynopsisArgs }}
-` + "```" + `{{ range $v := .SynopsisArgs }}
-{{ $v }}{{ end }}
 ` + "```" + `
+{{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}` + "```" + `
 {{ end }}{{ if .App.UsageText }}
 # DESCRIPTION
 

testdata/expected-doc-full.man

@@ -0,0 +1,80 @@
+.nh
+.TH greet(8) 
+
+.SH Harrison
+
+.SH NAME
+.PP
+greet \- Some app
+
+
+.SH SYNOPSIS
+.PP
+greet
+
+.PP
+.RS
+
+.nf
+[\-\-another\-flag|\-b]
+[\-\-flag|\-\-fl|\-f]=[value]
+[\-\-socket|\-s]=[value]
+
+.fi
+.RE
+
+
+.SH DESCRIPTION
+.PP
+app [first\_arg] [second\_arg]
+
+.PP
+\fBUsage\fP:
+
+.PP
+.RS
+
+.nf
+greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+
+.fi
+.RE
+
+
+.SH GLOBAL OPTIONS
+.PP
+\fB\-\-another\-flag, \-b\fP: another usage text
+
+.PP
+\fB\-\-flag, \-\-fl, \-f\fP="":
+
+.PP
+\fB\-\-socket, \-s\fP="": some usage text (default: value)
+
+
+.SH COMMANDS
+.SH config, c
+.PP
+another usage test
+
+.PP
+\fB\-\-another\-flag, \-b\fP: another usage text
+
+.PP
+\fB\-\-flag, \-\-fl, \-f\fP="":
+
+.SS sub\-config, s, ss
+.PP
+another usage test
+
+.PP
+\fB\-\-sub\-command\-flag, \-s\fP: some usage text
+
+.PP
+\fB\-\-sub\-flag, \-\-sub\-fl, \-s\fP="":
+
+.SH info, i, in
+.PP
+retrieve generic information
+
+.SH some\-command

testdata/expected-doc-full.md

@@ -0,0 +1,62 @@
+% greet(8) 
+
+% Harrison
+
+# 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
+
+

testdata/expected-doc-no-commands.md

@@ -0,0 +1,36 @@
+% greet(8) 
+
+% Harrison
+
+# 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)
+