Merge pull request #1 from urfave/extern-templates

Move templates from string literals to embedded strings

Author: meatballhat

.gitattributes

@@ -0,0 +1 @@
+*.gotmpl text eol=lf

docs.go

@@ -2,6 +2,7 @@ package docs
 
 import (
 	"bytes"
+	_ "embed"
 	"fmt"
 	"io"
 	"os"
@@ -18,6 +19,12 @@ import (
 )
 
 var (
+	//go:embed markdown.md.gotmpl
+	MarkdownDocTemplate string
+
+	//go:embed markdown_tabular.md.gotmpl
+	MarkdownTabularDocTemplate string
+
 	isTracingOn = os.Getenv("URFAVE_CLI_TRACING") == "on"
 )
 
@@ -114,7 +121,7 @@ func ToTabularToFileBetweenTags(cmd *cli.Command, appPath, filePath string, star
 		return err
 	}
 
-	const comment = "<!-- Documentation inside this block generated by github.com/urfave/cli; DO NOT EDIT -->"
+	const comment = "<!-- Documentation inside this block generated by github.com/urfave/cli-docs/v3; DO NOT EDIT -->"
 
 	// replace content between start and end tags
 	updated := re.ReplaceAll(content, []byte(strings.Join([]string{start, comment, md, end}, "\n")))

docs_test.go

@@ -2,6 +2,7 @@ package docs
 
 import (
 	"bytes"
+	"embed"
 	"io"
 	"io/fs"
 	"net/mail"
@@ -12,14 +13,30 @@ import (
 	"github.com/urfave/cli/v3"
 )
 
+var (
+	//go:embed testdata
+	testdata embed.FS
+)
+
 func expectFileContent(t *testing.T, file, got string) {
-	data, err := os.ReadFile(file)
-	// Ignore windows line endings
-	data = bytes.ReplaceAll(data, []byte("\r\n"), []byte("\n"))
+	data, err := testdata.ReadFile(file)
 
 	r := require.New(t)
 	r.NoError(err)
-	r.Equal(got, string(data))
+	r.Equal(
+		string(normalizeNewlines([]byte(got))),
+		string(normalizeNewlines(data)),
+	)
+}
+
+func normalizeNewlines(d []byte) []byte {
+	return bytes.ReplaceAll(
+		bytes.ReplaceAll(
+			d,
+			[]byte("\r\n"), []byte("\n"),
+		),
+		[]byte("\r"), []byte("\n"),
+	)
 }
 
 func buildExtendedTestCommand() *cli.Command {
@@ -137,13 +154,8 @@ Should be a part of the same code block
 }
 
 func TestToMarkdownFull(t *testing.T) {
-	// Given
 	cmd := buildExtendedTestCommand()
-
-	// When
 	res, err := ToMarkdown(cmd)
-
-	// Then
 	require.NoError(t, err)
 	expectFileContent(t, "testdata/expected-doc-full.md", res)
 }
@@ -152,28 +164,19 @@ func TestToTabularMarkdown(t *testing.T) {
 	app := buildExtendedTestCommand()
 
 	t.Run("full", func(t *testing.T) {
-		// When
 		res, err := ToTabularMarkdown(app, "app")
-
-		// Then
 		require.NoError(t, err)
 		expectFileContent(t, "testdata/expected-tabular-markdown-full.md", res)
 	})
 
 	t.Run("with empty path", func(t *testing.T) {
-		// When
 		res, err := ToTabularMarkdown(app, "")
-
-		// Then
 		require.NoError(t, err)
 		expectFileContent(t, "testdata/expected-tabular-markdown-full.md", res)
 	})
 
 	t.Run("with custom app path", func(t *testing.T) {
-		// When
 		res, err := ToTabularMarkdown(app, "/usr/local/bin")
-
-		// Then
 		require.NoError(t, err)
 		expectFileContent(t, "testdata/expected-tabular-markdown-custom-app-path.md", res)
 	})
@@ -183,7 +186,7 @@ func TestToTabularMarkdownFailed(t *testing.T) {
 	tpl := MarkdownTabularDocTemplate
 	t.Cleanup(func() { MarkdownTabularDocTemplate = tpl })
 
-	MarkdownTabularDocTemplate = "{{ .Foo }}" // invalid template
+	MarkdownTabularDocTemplate = "{{ .Foo }}"
 
 	app := buildExtendedTestCommand()
 
@@ -196,17 +199,11 @@ func TestToTabularMarkdownFailed(t *testing.T) {
 }
 
 func TestToTabularToFileBetweenTags(t *testing.T) {
-	expectedDocs, fErr := os.ReadFile("testdata/expected-tabular-markdown-full.md")
+	expectedDocs, fErr := testdata.ReadFile("testdata/expected-tabular-markdown-full.md")
 
 	r := require.New(t)
 	r.NoError(fErr)
 
-	// normalizes \r\n (windows) and \r (mac) into \n (unix) (required for tests to pass on windows)
-	normalizeNewlines := func(d []byte) []byte {
-		d = bytes.ReplaceAll(d, []byte{13, 10}, []byte{10}) // replace CR LF \r\n (windows) with LF \n (unix)
-		return bytes.ReplaceAll(d, []byte{13}, []byte{10})  // replace CF \r (mac) with LF \n (unix)
-	}
-
 	t.Run("default tags", func(t *testing.T) {
 		tmpFile, err := os.CreateTemp("", "")
 
@@ -238,7 +235,7 @@ Some other text`)
 Some description
 
 <!--GENERATED:CLI_DOCS-->
-<!-- Documentation inside this block generated by github.com/urfave/cli; DO NOT EDIT -->
+<!-- Documentation inside this block generated by github.com/urfave/cli-docs/v3; DO NOT EDIT -->
 ` + string(expectedDocs) + `
 <!--/GENERATED:CLI_DOCS-->
 
@@ -278,7 +275,7 @@ Some other text`)
 Some description
 
 foo_BAR|baz
-<!-- Documentation inside this block generated by github.com/urfave/cli; DO NOT EDIT -->
+<!-- Documentation inside this block generated by github.com/urfave/cli-docs/v3; DO NOT EDIT -->
 ` + string(expectedDocs) + `
 lorem+ipsum
 
@@ -302,44 +299,46 @@ Some other text`))
 	})
 }
 
-func TestToMarkdownNoFlags(t *testing.T) {
-	app := buildExtendedTestCommand()
-	app.Flags = nil
+func TestToMarkdown(t *testing.T) {
+	t.Run("no flags", func(t *testing.T) {
+		app := buildExtendedTestCommand()
+		app.Flags = nil
 
-	res, err := ToMarkdown(app)
+		res, err := ToMarkdown(app)
 
-	require.NoError(t, err)
-	expectFileContent(t, "testdata/expected-doc-no-flags.md", res)
-}
+		require.NoError(t, err)
+		expectFileContent(t, "testdata/expected-doc-no-flags.md", res)
+	})
 
-func TestToMarkdownNoCommands(t *testing.T) {
-	app := buildExtendedTestCommand()
-	app.Commands = nil
+	t.Run("no commands", func(t *testing.T) {
+		app := buildExtendedTestCommand()
+		app.Commands = nil
 
-	res, err := ToMarkdown(app)
+		res, err := ToMarkdown(app)
 
-	require.NoError(t, err)
-	expectFileContent(t, "testdata/expected-doc-no-commands.md", res)
-}
+		require.NoError(t, err)
+		expectFileContent(t, "testdata/expected-doc-no-commands.md", res)
+	})
 
-func TestToMarkdownNoAuthors(t *testing.T) {
-	app := buildExtendedTestCommand()
-	app.Authors = []any{}
+	t.Run("no authors", func(t *testing.T) {
+		app := buildExtendedTestCommand()
+		app.Authors = []any{}
 
-	res, err := ToMarkdown(app)
+		res, err := ToMarkdown(app)
 
-	require.NoError(t, err)
-	expectFileContent(t, "testdata/expected-doc-no-authors.md", res)
-}
+		require.NoError(t, err)
+		expectFileContent(t, "testdata/expected-doc-no-authors.md", res)
+	})
 
-func TestToMarkdownNoUsageText(t *testing.T) {
-	app := buildExtendedTestCommand()
-	app.UsageText = ""
+	t.Run("no usage text", func(t *testing.T) {
+		app := buildExtendedTestCommand()
+		app.UsageText = ""
 
-	res, err := ToMarkdown(app)
+		res, err := ToMarkdown(app)
 
-	require.NoError(t, err)
-	expectFileContent(t, "testdata/expected-doc-no-usagetext.md", res)
+		require.NoError(t, err)
+		expectFileContent(t, "testdata/expected-doc-no-usagetext.md", res)
+	})
 }
 
 func TestToMan(t *testing.T) {

markdown.md.gotmpl

@@ -0,0 +1,32 @@
+{{if gt .SectionNum 0}}% {{ .Command.Name }} {{ .SectionNum }}
+
+{{end}}# NAME
+
+{{ .Command.Name }}{{ if .Command.Usage }} - {{ .Command.Usage }}{{ end }}
+
+# SYNOPSIS
+
+{{ .Command.Name }}
+{{ if .SynopsisArgs }}
+```
+{{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}```
+{{ end }}{{ if .Command.Description }}
+# DESCRIPTION
+
+{{ .Command.Description }}
+{{ end }}
+**Usage**:
+
+```{{ if .Command.UsageText }}
+{{ .Command.UsageText }}
+{{ else }}
+{{ .Command.Name }} [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
+{{ end }}```
+{{ if .GlobalArgs }}
+# GLOBAL OPTIONS
+{{ range $v := .GlobalArgs }}
+{{ $v }}{{ end }}
+{{ end }}{{ if .Commands }}
+# COMMANDS
+{{ range $v := .Commands }}
+{{ $v }}{{ end }}{{ end -}}

markdown_tabular.md.gotmpl

@@ -0,0 +1,71 @@
+{{ define "flags" }}
+| Name | Description | Default value | Environment variables |
+|------|-------------|:-------------:|:---------------------:|
+{{   range $flag := . -}}
+{{- /**/ -}} | `{{ $flag.Name }}{{ if $flag.TakesValue }}="…"{{ end }}` {{ if $flag.Aliases }}(`{{ join $flag.Aliases "`, `" }}`) {{ end }}
+{{- /**/ -}} | {{ $flag.Usage }}
+{{- /**/ -}} | {{ if $flag.Default }}`{{ $flag.Default }}`{{ end }}
+{{- /**/ -}} | {{ if $flag.EnvVars }}`{{ join $flag.EnvVars "`, `" }}`{{ else }}*none*{{ end }}
+{{- /**/ -}} |
+{{   end }}
+{{ end }}
+
+{{ define "command" }}
+### `{{ .Name }}` {{ if gt .Level 0 }}sub{{ end }}command{{ if .Aliases }} (aliases: `{{ join .Aliases "`, `" }}`){{ end }}
+{{   if .Usage }}
+{{     .Usage }}.
+{{   end }}
+{{   if .UsageText }}
+{{     range $line := .UsageText -}}
+> {{ $line }}
+{{     end -}}
+{{   end }}
+{{   if .Description }}
+{{     .Description }}.
+{{   end }}
+Usage:
+
+```bash
+$ {{ .AppPath }} [GLOBAL FLAGS] {{ .Name }}{{ if .Flags }} [COMMAND FLAGS]{{ end }} {{ if .ArgsUsage }}{{ .ArgsUsage }}{{ else }}[ARGUMENTS...]{{ end }}
+```
+
+{{   if .Flags -}}
+The following flags are supported:
+{{     template "flags" .Flags }}
+{{   end -}}
+
+{{   if .SubCommands -}}
+{{     range $subCmd := .SubCommands -}}
+{{       template "command" $subCmd }}
+{{     end -}}
+{{   end -}}
+{{ end }}
+
+## CLI interface{{ if .Name }} - {{ .Name }}{{ end }}
+
+{{ if .Description }}{{ .Description }}.
+{{ end }}
+{{ if .Usage }}{{ .Usage }}.
+{{ end }}
+{{ if .UsageText }}
+{{   range $line := .UsageText -}}
+> {{ $line }}
+{{   end -}}
+{{ end }}
+Usage:
+
+```bash
+$ {{ .AppPath }}{{ if .GlobalFlags }} [GLOBAL FLAGS]{{ end }} [COMMAND] [COMMAND FLAGS] {{ if .ArgsUsage }}{{ .ArgsUsage }}{{ else }}[ARGUMENTS...]{{ end }}
+```
+
+{{ if .GlobalFlags }}
+Global flags:
+
+{{ template "flags" .GlobalFlags }}
+
+{{ end -}}
+{{ if .Commands -}}
+{{   range $cmd := .Commands -}}
+{{     template "command" $cmd }}
+{{   end }}
+{{- end }}