From 0856a41798bd1168b78260585ec8d9479d1b33fd Mon Sep 17 00:00:00 2001 From: Alexander Miranda Date: Wed, 19 Jun 2024 12:49:21 -0500 Subject: [PATCH 1/4] feat: #1140 adding GenMarkdownTreeCustomWithFooter method --- doc/md_docs.go | 31 +++++++++++++++++++++++++++++++ doc/md_docs_test.go | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/doc/md_docs.go b/doc/md_docs.go index 1259222..69aef29 100644 --- a/doc/md_docs.go +++ b/doc/md_docs.go @@ -156,3 +156,34 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa } return nil } + +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 +} diff --git a/doc/md_docs_test.go b/doc/md_docs_test.go index e70cad8..7b317d3 100644 --- a/doc/md_docs_test.go +++ b/doc/md_docs_test.go @@ -124,3 +124,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 "Postpended" } + 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, "Postpended") + + gotEcho := fileContents(t, tmpdir, "root_echo.md") + checkStringContains(t, gotEcho, "Prepended") + checkStringContains(t, gotEcho, echoCmd.Long) + checkStringContains(t, gotEcho, "Postpended") + + gotEchoSub := fileContents(t, tmpdir, "root_echo_echosub.md") + checkStringContains(t, gotEchoSub, "Prepended") + checkStringContains(t, gotEchoSub, echoSubCmd.Long) + checkStringContains(t, gotEchoSub, "Postpended") +} + +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) +} From b522459430b52290450dc9f83ab1bd4208304365 Mon Sep 17 00:00:00 2001 From: Alexander Miranda Date: Wed, 19 Jun 2024 12:55:06 -0500 Subject: [PATCH 2/4] feat: #1140 updating test values to match with callback name --- doc/md_docs_test.go | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/md_docs_test.go b/doc/md_docs_test.go index 7b317d3..4abf86e 100644 --- a/doc/md_docs_test.go +++ b/doc/md_docs_test.go @@ -133,7 +133,7 @@ func TestGenMdTreeCustomWithFooter(t *testing.T) { defer os.RemoveAll(tmpdir) prepender := func(s string) string { return "Prepended" } - appender := func(s string) string { return "Postpended" } + appender := func(s string) string { return "Appended" } identity := func(s string) string { return s } if err := GenMarkdownTreeCustomWithFooter(rootCmd, tmpdir, prepender, appender, identity); err != nil { @@ -143,17 +143,17 @@ func TestGenMdTreeCustomWithFooter(t *testing.T) { gotRoot := fileContents(t, tmpdir, "root.md") checkStringContains(t, gotRoot, "Prepended") checkStringContains(t, gotRoot, rootCmd.Long) - checkStringContains(t, gotRoot, "Postpended") + checkStringContains(t, gotRoot, "Appended") gotEcho := fileContents(t, tmpdir, "root_echo.md") checkStringContains(t, gotEcho, "Prepended") checkStringContains(t, gotEcho, echoCmd.Long) - checkStringContains(t, gotEcho, "Postpended") + checkStringContains(t, gotEcho, "Appended") gotEchoSub := fileContents(t, tmpdir, "root_echo_echosub.md") checkStringContains(t, gotEchoSub, "Prepended") checkStringContains(t, gotEchoSub, echoSubCmd.Long) - checkStringContains(t, gotEchoSub, "Postpended") + checkStringContains(t, gotEchoSub, "Appended") } func fileContents(t *testing.T, dir, filename string) string { From c71ca75519c1a75e376f189ecb8ef373ba02e7eb Mon Sep 17 00:00:00 2001 From: Alexander Miranda Date: Wed, 19 Jun 2024 12:59:33 -0500 Subject: [PATCH 3/4] feat: #1140 added godoc --- doc/md_docs.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/md_docs.go b/doc/md_docs.go index 69aef29..6623d50 100644 --- a/doc/md_docs.go +++ b/doc/md_docs.go @@ -157,6 +157,8 @@ 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() { From 53bc9d32190af3ba5a7def9593c4d94c8747817a Mon Sep 17 00:00:00 2001 From: Alexander Miranda Date: Wed, 19 Jun 2024 13:31:07 -0500 Subject: [PATCH 4/4] feat: #1140 updating doc gen docs for new method --- site/content/docgen/md.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/site/content/docgen/md.md b/site/content/docgen/md.md index 1659175..c687314 100644 --- a/site/content/docgen/md.md +++ b/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