Merge 53bc9d3219 into 02326d52c0

doc/md_docs.go

@@ -156,3 +156,36 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa
 	}
 	return nil
 }
+
+// GenMarkdownTreeCustomWithFooter is the same as GenMarkdownTree, but
+// with custom filePrepender, fileAppender, and linkHandler.
+func GenMarkdownTreeCustomWithFooter(
+	cmd *cobra.Command, dir string, filePrepender, fileAppender, linkHandler func(string) string) error {
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		if err := GenMarkdownTreeCustomWithFooter(c, dir, filePrepender, fileAppender, linkHandler); err != nil {
+			return err
+		}
+	}
+
+	basename := strings.ReplaceAll(cmd.CommandPath(), " ", "_") + markdownExtension
+	filename := filepath.Join(dir, basename)
+	f, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
+		return err
+	}
+	if err := GenMarkdownCustom(cmd, f, linkHandler); err != nil {
+		return err
+	}
+	if _, err := io.WriteString(f, fileAppender(filename)); err != nil {
+		return err
+	}
+	return nil
+}

doc/md_docs_test.go

@@ -123,3 +123,42 @@ func BenchmarkGenMarkdownToFile(b *testing.B) {
 		}
 	}
 }
+
+func TestGenMdTreeCustomWithFooter(t *testing.T) {
+	tmpdir, err := ioutil.TempDir("", "test-gen-md-tree")
+	if err != nil {
+		t.Fatalf("Failed to create tmpdir: %v", err)
+	}
+	defer os.RemoveAll(tmpdir)
+
+	prepender := func(s string) string { return "Prepended" }
+	appender := func(s string) string { return "Appended" }
+	identity := func(s string) string { return s }
+
+	if err := GenMarkdownTreeCustomWithFooter(rootCmd, tmpdir, prepender, appender, identity); err != nil {
+		t.Fatalf("GenMarkdownTree failed: %v", err)
+	}
+
+	gotRoot := fileContents(t, tmpdir, "root.md")
+	checkStringContains(t, gotRoot, "Prepended")
+	checkStringContains(t, gotRoot, rootCmd.Long)
+	checkStringContains(t, gotRoot, "Appended")
+
+	gotEcho := fileContents(t, tmpdir, "root_echo.md")
+	checkStringContains(t, gotEcho, "Prepended")
+	checkStringContains(t, gotEcho, echoCmd.Long)
+	checkStringContains(t, gotEcho, "Appended")
+
+	gotEchoSub := fileContents(t, tmpdir, "root_echo_echosub.md")
+	checkStringContains(t, gotEchoSub, "Prepended")
+	checkStringContains(t, gotEchoSub, echoSubCmd.Long)
+	checkStringContains(t, gotEchoSub, "Appended")
+}
+
+func fileContents(t *testing.T, dir, filename string) string {
+	contents, err := ioutil.ReadFile(filepath.Join(dir, filename))
+	if err != nil {
+		t.Fatalf("Error loading file %q: %v ", filename, err)
+	}
+	return string(contents)
+}

site/content/docgen/md.md

@@ -79,6 +79,12 @@ func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler
 }
 ```
 
+```go
+func GenMarkdownTreeCustomWithFooter(cmd *Command, dir string, filePrepender, fileAppender, linkHandler func(string) string) error {
+	//...
+}
+```
+
 ```go
 func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
 	//...
@@ -105,6 +111,8 @@ filePrepender := func(filename string) string {
 }
 ```
 
+The `fileAppender` will append the return value given the full filepath to the rendered Markdown file.
+
 The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename:
 
 ```go