From b300764031d78c1526ecee7ef4c0083cb65e7114 Mon Sep 17 00:00:00 2001 From: linuxboytoo Date: Wed, 20 Oct 2021 22:59:44 -0500 Subject: [PATCH] added custom footer options to md-docs-generator (spf13#1140) --- doc/cmd_test.go | 10 +++++++ doc/md_docs.go | 18 ++++++++++--- doc/md_docs_test.go | 63 +++++++++++++++++++++++++++++++++++++++++++++ go.mod | 3 +++ go.sum | 17 ++++++++++++ 5 files changed, 107 insertions(+), 4 deletions(-) diff --git a/doc/cmd_test.go b/doc/cmd_test.go index 0917d602..dc12f806 100644 --- a/doc/cmd_test.go +++ b/doc/cmd_test.go @@ -1,6 +1,8 @@ package doc import ( + "io/ioutil" + "path/filepath" "strings" "testing" @@ -89,3 +91,11 @@ func checkStringOmits(t *testing.T, got, expected string) { t.Errorf("Expected to not contain: \n %v\nGot: %v", expected, got) } } + +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) +} diff --git a/doc/md_docs.go b/doc/md_docs.go index 5181af8d..7b3dd512 100644 --- a/doc/md_docs.go +++ b/doc/md_docs.go @@ -122,17 +122,24 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) func GenMarkdownTree(cmd *cobra.Command, dir string) error { identity := func(s string) string { return s } emptyStr := func(s string) string { return "" } - return GenMarkdownTreeCustom(cmd, dir, emptyStr, identity) + return GenMarkdownTreeCustomHeaderAndFooter(cmd, dir, emptyStr, emptyStr, identity) } -// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but -// with custom filePrepender and linkHandler. +// GenMarkdownTreeCustom is here to maintain backwards compatibility +// until this method can be deprecated. It only supports a custom header func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error { + emptyStr := func(s string) string { return "" } + return GenMarkdownTreeCustomHeaderAndFooter(cmd, dir, filePrepender, emptyStr, linkHandler) +} + +// GenMarkdownTreeCustomHeaderAndFooter is the the same as GenMarkdownTree, but +// with custom filePrepender, filePostpender and linkHandler. +func GenMarkdownTreeCustomHeaderAndFooter(cmd *cobra.Command, dir string, filePrepender, filePostpender, linkHandler func(string) string) error { for _, c := range cmd.Commands() { if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { continue } - if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil { + if err := GenMarkdownTreeCustomHeaderAndFooter(c, dir, filePrepender, filePostpender, linkHandler); err != nil { return err } } @@ -151,5 +158,8 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa if err := GenMarkdownCustom(cmd, f, linkHandler); err != nil { return err } + if _, err := io.WriteString(f, filePostpender(filename)); err != nil { + return err + } return nil } diff --git a/doc/md_docs_test.go b/doc/md_docs_test.go index f3251679..fb287dad 100644 --- a/doc/md_docs_test.go +++ b/doc/md_docs_test.go @@ -2,10 +2,12 @@ package doc import ( "bytes" + "fmt" "io/ioutil" "os" "path/filepath" "testing" + "time" "github.com/spf13/cobra" ) @@ -110,3 +112,64 @@ func BenchmarkGenMarkdownToFile(b *testing.B) { } } } + +func TestGenMdTreeCustom(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" } + identity := func(s string) string { return s } + + if err := GenMarkdownTreeCustom(rootCmd, tmpdir, prepender, identity); err != nil { + t.Fatalf("GenMarkdownTree failed: %v", err) + } + + gotRoot := fileContents(t, tmpdir, "root.md") + checkStringContains(t, gotRoot, "Prepended") + checkStringContains(t, gotRoot, rootCmd.Long) + + gotEcho := fileContents(t, tmpdir, "root_echo.md") + checkStringContains(t, gotEcho, "Prepended") + checkStringContains(t, gotEcho, echoCmd.Long) + + gotEchoSub := fileContents(t, tmpdir, "root_echo_echosub.md") + checkStringContains(t, gotEchoSub, "Prepended") + checkStringContains(t, gotEchoSub, echoSubCmd.Long) +} + +func TestGenMarkdownTreeCustomHeaderAndFooter(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) + + prependStr := fmt.Sprintf("pre%d", time.Now().UnixNano()) + postpendStr := fmt.Sprintf("post%d", time.Now().UnixNano()) + + prepender := func(s string) string { return prependStr } + identity := func(s string) string { return s } + postpender := func(s string) string { return postpendStr } + + if err := GenMarkdownTreeCustomHeaderAndFooter(rootCmd, tmpdir, prepender, postpender, identity); err != nil { + t.Fatalf("GenMarkdownTree failed: %v", err) + } + + gotRoot := fileContents(t, tmpdir, "root.md") + checkStringContains(t, gotRoot, prependStr) + checkStringContains(t, gotRoot, rootCmd.Long) + checkStringContains(t, gotRoot, postpendStr) + + gotEcho := fileContents(t, tmpdir, "root_echo.md") + checkStringContains(t, gotEcho, prependStr) + checkStringContains(t, gotEcho, echoCmd.Long) + checkStringContains(t, gotEcho, postpendStr) + + gotEchoSub := fileContents(t, tmpdir, "root_echo_echosub.md") + checkStringContains(t, gotEchoSub, prependStr) + checkStringContains(t, gotEchoSub, echoSubCmd.Long) + checkStringContains(t, gotEchoSub, postpendStr) +} diff --git a/go.mod b/go.mod index 97eab3c9..d0631967 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,10 @@ go 1.15 require ( github.com/cpuguy83/go-md2man/v2 v2.0.1 github.com/inconshreveable/mousetrap v1.0.0 + github.com/kyoh86/richgo v0.3.9 // indirect + github.com/mattn/go-isatty v0.0.14 // indirect github.com/spf13/pflag v1.0.5 github.com/spf13/viper v1.8.1 + golang.org/x/sys v0.0.0-20211020174200-9d6173849985 // indirect gopkg.in/yaml.v2 v2.4.0 ) diff --git a/go.sum b/go.sum index 6e832371..76f200f8 100644 --- a/go.sum +++ b/go.sum @@ -178,10 +178,17 @@ github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORN github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE= github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= +github.com/kyoh86/richgo v0.3.9 h1:om0AqQ6LmNYvaL7pMK7s3gixTM6iWzH3ICkfS0qNs+k= +github.com/kyoh86/richgo v0.3.9/go.mod h1:2C8POkF1H04iTOG2Tp1yyZhspCME9nN3cir3VXJ02II= +github.com/kyoh86/xdg v1.2.0 h1:CERuT/ShdTDj+A2UaX3hQ3mOV369+Sj+wyn2nIRIIkI= +github.com/kyoh86/xdg v1.2.0/go.mod h1:/mg8zwu1+qe76oTFUBnyS7rJzk7LLC0VGEzJyJ19DHs= github.com/magiconair/properties v1.8.5 h1:b6kJs+EmPFMYGkow9GiUyCyOvIwYetYJ3fSaWak/Gls= github.com/magiconair/properties v1.8.5/go.mod h1:y3VJvCyxH9uVvJTWEGAELF3aiYNyPKd5NZ3oSwXrF60= github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU= github.com/mattn/go-isatty v0.0.3/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4= +github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU= +github.com/mattn/go-isatty v0.0.14 h1:yVuAays6BHfxijgZPzw+3Zlu5yQgKGP2/hcQbHb7S9Y= +github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94= github.com/miekg/dns v1.0.14/go.mod h1:W1PPwlIAgtquWBMBEV9nkV9Cazfe8ScdGz/Lj7v3Nrg= github.com/mitchellh/cli v1.0.0/go.mod h1:hNIlj7HEI86fIcpObd7a0FcrxTWetlwJDGcceTlRvqc= github.com/mitchellh/go-homedir v1.0.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0= @@ -195,6 +202,8 @@ github.com/mitchellh/mapstructure v1.4.1/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RR github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0= github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0= +github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A= +github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc= github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc= github.com/pelletier/go-toml v1.9.3 h1:zeC5b1GviRUyKYd6OJPvBU/mcVDVoL1OhT17FCt5dSQ= github.com/pelletier/go-toml v1.9.3/go.mod h1:u1nR/EPcESfeI/szUZKdtJ0xRNbUoANCkoOuaOx1Y+c= @@ -204,6 +213,7 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/posener/complete v1.1.1/go.mod h1:em0nMJCgc9GFtwrmVmEMR/ZL6WyhyjMBndrE9hABlRI= github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA= +github.com/rakyll/statik v0.1.7/go.mod h1:AlZONWzMtEnMs7W4e/1LURLiI49pIMmp6V9Unghqrcc= github.com/rogpeppe/fastuuid v1.2.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ= github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4= github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= @@ -234,6 +244,8 @@ github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5Cc github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/subosito/gotenv v1.2.0 h1:Slr1R9HxAlEKefgq5jn9U+DnETlIUa6HfgEzj0g5d7s= github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw= +github.com/wacul/ptr v1.0.0 h1:FIKu08Wx0YUIf9MNsfF62OCmBSmz5A1Tk65zWhOIL/I= +github.com/wacul/ptr v1.0.0/go.mod h1:BD0gjsZrCwtoR+yWDB9v2hQ8STlq9tT84qKfa+3txOc= github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= @@ -369,6 +381,7 @@ golang.org/x/sys v0.0.0-20191005200804-aed5e4c7ecf9/go.mod h1:h1NjWce9XRLGQEsW7w golang.org/x/sys v0.0.0-20191204072324-ce4227a45e2e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20191228213918-04cbcbbfeed8/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200113162924-86b910548bc1/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200122134326-e047566fdf82/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200202164722-d101bd2416d5/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200212091648-12a6c2dcc1e4/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= @@ -391,10 +404,14 @@ golang.org/x/sys v0.0.0-20210220050731-9a76102bfb43/go.mod h1:h1NjWce9XRLGQEsW7w golang.org/x/sys v0.0.0-20210305230114-8fe3ee5dd75b/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210315160823-c6e025ad8005/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210320140829-1e4c9ba3b0c4/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20210326220804-49726bf1d181/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210403161142-5e06dd20ab57/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210510120138-977fb7262007 h1:gG67DSER+11cZvqIMb8S8bt0vZtiN6xWYARwirrOSfE= golang.org/x/sys v0.0.0-20210510120138-977fb7262007/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20211020174200-9d6173849985 h1:LOlKVhfDyahgmqa97awczplwkjzNaELFg3zRIJ13RYo= +golang.org/x/sys v0.0.0-20211020174200-9d6173849985/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=