CLOUDP-303339 Added support for custom example formatting + snapshotting tests (#67)

Co-authored-by: Gustavo Bazan <[email protected]>

Author: jeroenvervaeke

.snapshots/custom_formatter_example.txt

@@ -0,0 +1,42 @@
+.. _custom_example:
+
+==============
+custom_example
+==============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+
+
+Testing example output using a custom example formatter
+
+Options
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 10 10 60
+
+   * - Name
+     - Type
+     - Required
+     - Description
+   * - -h, --help
+     - 
+     - false
+     - help for custom_example
+
+custom example for custom_example
+example --test -v
+.. toctree::
+   :titlesonly:
+
+
+*Auto generated by cobra2snooty on 5-Mar-2025*
+

.snapshots/custom_formatter_surround_default_example.txt

@@ -0,0 +1,50 @@
+.. _custom_formatter_surround_default_example:
+
+=========================================
+custom_formatter_surround_default_example
+=========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+
+
+Testing example output using a custom example formatter which calls the default formatter
+
+Options
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 10 10 60
+
+   * - Name
+     - Type
+     - Required
+     - Description
+   * - -h, --help
+     - 
+     - false
+     - help for custom_formatter_surround_default_example
+
+-- before example --
+Examples
+--------
+
+.. code-block::
+   :copyable: false
+
+   example --test -v
+-- after example --
+
+.. toctree::
+   :titlesonly:
+
+
+*Auto generated by cobra2snooty on 5-Mar-2025*
+

.snapshots/default_example.txt

@@ -0,0 +1,48 @@
+.. _default_example:
+
+===============
+default_example
+===============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+
+
+Testing example output using the default example formatter
+
+Options
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 10 10 60
+
+   * - Name
+     - Type
+     - Required
+     - Description
+   * - -h, --help
+     - 
+     - false
+     - help for default_example
+
+Examples
+--------
+
+.. code-block::
+   :copyable: false
+
+   example --test -v
+
+.. toctree::
+   :titlesonly:
+
+
+*Auto generated by cobra2snooty on 5-Mar-2025*
+

cobra2snooty.go

@@ -80,10 +80,12 @@ const tocHeader = `
 
 // GenDocs creates snooty help output.
 // Adapted from https://github.com/spf13/cobra/tree/master/doc to match MongoDB tooling and style.
-func GenDocs(cmd *cobra.Command, w io.Writer) error {
+func GenDocs(cmd *cobra.Command, w io.Writer, genDocOptions ...GenDocsOption) error {
 	cmd.InitDefaultHelpCmd()
 	cmd.InitDefaultHelpFlag()
 
+	options := newGenDocsOptions(genDocOptions)
+
 	buf := new(bytes.Buffer)
 	name := cmd.CommandPath()
 
@@ -117,9 +119,7 @@ func GenDocs(cmd *cobra.Command, w io.Writer) error {
 
 	printOutputCreate(buf, cmd)
 
-	if cmd.Example != "" {
-		printExamples(buf, cmd)
-	}
+	options.exampleFormatter(buf, cmd)
 
 	if hasRelatedCommands(cmd) {
 		buf.WriteString("Related Commands\n")
@@ -156,7 +156,7 @@ func GenDocs(cmd *cobra.Command, w io.Writer) error {
 	}
 
 	if !cmd.DisableAutoGenTag {
-		buf.WriteString("*Auto generated by cobra2snooty on " + time.Now().Format("2-Jan-2006") + "*\n")
+		buf.WriteString("*Auto generated by cobra2snooty on " + options.timeGetter().Format("2-Jan-2006") + "*\n")
 	}
 	_, err := buf.WriteTo(w)
 	return err
@@ -196,3 +196,33 @@ type byName []*cobra.Command
 func (s byName) Len() int           { return len(s) }
 func (s byName) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }
 func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }
+
+type GenDocsOptions struct {
+	exampleFormatter func(buf *bytes.Buffer, cmd *cobra.Command)
+	timeGetter       func() time.Time
+}
+
+func newGenDocsOptions(options []GenDocsOption) *GenDocsOptions {
+	o := &GenDocsOptions{
+		exampleFormatter: DefaultExampleFormatter,
+		timeGetter:       DefaultTimeGetter,
+	}
+
+	for _, option := range options {
+		option(o)
+	}
+
+	return o
+}
+
+type GenDocsOption = func(options *GenDocsOptions)
+
+func DefaultTimeGetter() time.Time {
+	return time.Now()
+}
+
+func WithCustomTimeGetter(customTimeGetter func() time.Time) func(options *GenDocsOptions) {
+	return func(options *GenDocsOptions) {
+		options.timeGetter = customTimeGetter
+	}
+}

cobra2snooty_test.go

@@ -21,7 +21,9 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
+	"github.com/bradleyjkemp/cupaloy/v2"
 	"github.com/spf13/cobra"
 )
 
@@ -282,3 +284,84 @@ func TestArgsRegex(t *testing.T) {
 		}
 	})
 }
+
+// To update snapshots run: UPDATE_SNAPSHOTS=true go test ./...
+func TestGenDocsSnapshots(t *testing.T) {
+	// Test cases
+	tests := []struct {
+		name    string
+		cmd     *cobra.Command
+		options []GenDocsOption
+	}{
+		{
+			name: "default_example",
+			cmd: &cobra.Command{
+				Use:     "default_example",
+				Long:    "Testing example output using the default example formatter",
+				Example: "example --test -v",
+			},
+			options: []GenDocsOption{
+				WithCustomTimeGetter(func() time.Time {
+					return time.Date(2025, 3, 5, 17, 0, 0, 0, time.UTC)
+				}),
+			},
+		},
+		{
+			name: "custom_formatter_example",
+			cmd: &cobra.Command{
+				Use:     "custom_example",
+				Long:    "Testing example output using a custom example formatter",
+				Example: "example --test -v",
+			},
+			options: []GenDocsOption{
+				WithCustomTimeGetter(func() time.Time {
+					return time.Date(2025, 3, 5, 17, 0, 0, 0, time.UTC)
+				}),
+				WithCustomExampleFormatter(func(buf *bytes.Buffer, cmd *cobra.Command) {
+					_, _ = fmt.Fprintf(buf, "custom example for %s\n", cmd.Use)
+					_, _ = buf.WriteString(cmd.Example)
+				}),
+			},
+		},
+		{
+			name: "custom_formatter_surround_default_example",
+			cmd: &cobra.Command{
+				Use:     "custom_formatter_surround_default_example",
+				Long:    "Testing example output using a custom example formatter which calls the default formatter",
+				Example: "example --test -v",
+			},
+			options: []GenDocsOption{
+				WithCustomTimeGetter(func() time.Time {
+					return time.Date(2025, 3, 5, 17, 0, 0, 0, time.UTC)
+				}),
+				WithCustomExampleFormatter(func(buf *bytes.Buffer, cmd *cobra.Command) {
+					_, _ = buf.WriteString("-- before example --\n")
+					DefaultExampleFormatter(buf, cmd)
+					_, _ = buf.WriteString("-- after example --\n")
+				}),
+			},
+		},
+	}
+
+	// Run tests
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			snapshotter := cupaloy.New(cupaloy.SnapshotFileExtension(".txt"))
+			// Create buffer to capture output
+			buf := new(bytes.Buffer)
+
+			// Execute function
+			err := GenDocs(tt.cmd, buf, tt.options...)
+			if err != nil {
+				t.Fatalf("GenDocs() error = %v", err)
+				return
+			}
+
+			// Compare with snapshot
+			err = snapshotter.SnapshotWithName(tt.name, buf.String())
+			if err != nil {
+				t.Errorf("Snapshot comparison failed: %v", err)
+			}
+		})
+	}
+}

examples.go

@@ -30,6 +30,18 @@ const (
 	identChar = " "
 )
 
+func DefaultExampleFormatter(buf *bytes.Buffer, cmd *cobra.Command) {
+	if cmd.Example != "" {
+		printExamples(buf, cmd)
+	}
+}
+
+func WithCustomExampleFormatter(customFormatter func(buf *bytes.Buffer, cmd *cobra.Command)) func(options *GenDocsOptions) {
+	return func(options *GenDocsOptions) {
+		options.exampleFormatter = customFormatter
+	}
+}
+
 func printExamples(buf *bytes.Buffer, cmd *cobra.Command) {
 	// Create example substrings
 	examplestrimmed := strings.TrimLeft(cmd.Example, " #")

go.mod

@@ -3,8 +3,13 @@ module github.com/mongodb-labs/cobra2snooty
 go 1.20
 
 require (
+	github.com/bradleyjkemp/cupaloy/v2 v2.8.0
 	github.com/spf13/cobra v1.9.1
 	github.com/spf13/pflag v1.0.6
 )
 
-require github.com/inconshreveable/mousetrap v1.1.0 // indirect
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+)

go.sum

@@ -1,10 +1,21 @@
+github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M=
+github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
 github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
 github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
 github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.1.1/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=