Skip to content

Commit c6158d5

Browse files
jeroenvervaekegssbzn
jeroenvervaeke
and
gssbzn
authored
CLOUDP-303339 Added support for custom example formatting + snapshotting tests (#67)
Co-authored-by: Gustavo Bazan <[email protected]>
1 parent ac28c40 commit c6158d5

File tree

8 files changed

+287
-6
lines changed

8 files changed

+287
-6
lines changed

‎.snapshots/custom_formatter_example.txt‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.. _custom_example:
2+
3+
==============
4+
custom_example
5+
==============
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
16+
17+
Testing example output using a custom example formatter
18+
19+
Options
20+
-------
21+
22+
.. list-table::
23+
:header-rows: 1
24+
:widths: 20 10 10 60
25+
26+
* - Name
27+
- Type
28+
- Required
29+
- Description
30+
* - -h, --help
31+
-
32+
- false
33+
- help for custom_example
34+
35+
custom example for custom_example
36+
example --test -v
37+
.. toctree::
38+
:titlesonly:
39+
40+
41+
*Auto generated by cobra2snooty on 5-Mar-2025*
42+

‎.snapshots/custom_formatter_surround_default_example.txt‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. _custom_formatter_surround_default_example:
2+
3+
=========================================
4+
custom_formatter_surround_default_example
5+
=========================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
16+
17+
Testing example output using a custom example formatter which calls the default formatter
18+
19+
Options
20+
-------
21+
22+
.. list-table::
23+
:header-rows: 1
24+
:widths: 20 10 10 60
25+
26+
* - Name
27+
- Type
28+
- Required
29+
- Description
30+
* - -h, --help
31+
-
32+
- false
33+
- help for custom_formatter_surround_default_example
34+
35+
-- before example --
36+
Examples
37+
--------
38+
39+
.. code-block::
40+
:copyable: false
41+
42+
example --test -v
43+
-- after example --
44+
45+
.. toctree::
46+
:titlesonly:
47+
48+
49+
*Auto generated by cobra2snooty on 5-Mar-2025*
50+

‎.snapshots/default_example.txt‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
.. _default_example:
2+
3+
===============
4+
default_example
5+
===============
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
16+
17+
Testing example output using the default example formatter
18+
19+
Options
20+
-------
21+
22+
.. list-table::
23+
:header-rows: 1
24+
:widths: 20 10 10 60
25+
26+
* - Name
27+
- Type
28+
- Required
29+
- Description
30+
* - -h, --help
31+
-
32+
- false
33+
- help for default_example
34+
35+
Examples
36+
--------
37+
38+
.. code-block::
39+
:copyable: false
40+
41+
example --test -v
42+
43+
.. toctree::
44+
:titlesonly:
45+
46+
47+
*Auto generated by cobra2snooty on 5-Mar-2025*
48+

‎cobra2snooty.go‎

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -80,10 +80,12 @@ const tocHeader = `
8080

8181
// GenDocs creates snooty help output.
8282
// Adapted from https://github.com/spf13/cobra/tree/master/doc to match MongoDB tooling and style.
83-
func GenDocs(cmd *cobra.Command, w io.Writer) error {
83+
func GenDocs(cmd *cobra.Command, w io.Writer, genDocOptions ...GenDocsOption) error {
8484
cmd.InitDefaultHelpCmd()
8585
cmd.InitDefaultHelpFlag()
8686

87+
options := newGenDocsOptions(genDocOptions)
88+
8789
buf := new(bytes.Buffer)
8890
name := cmd.CommandPath()
8991

@@ -117,9 +119,7 @@ func GenDocs(cmd *cobra.Command, w io.Writer) error {
117119

118120
printOutputCreate(buf, cmd)
119121

120-
if cmd.Example != "" {
121-
printExamples(buf, cmd)
122-
}
122+
options.exampleFormatter(buf, cmd)
123123

124124
if hasRelatedCommands(cmd) {
125125
buf.WriteString("Related Commands\n")
@@ -156,7 +156,7 @@ func GenDocs(cmd *cobra.Command, w io.Writer) error {
156156
}
157157

158158
if !cmd.DisableAutoGenTag {
159-
buf.WriteString("*Auto generated by cobra2snooty on " + time.Now().Format("2-Jan-2006") + "*\n")
159+
buf.WriteString("*Auto generated by cobra2snooty on " + options.timeGetter().Format("2-Jan-2006") + "*\n")
160160
}
161161
_, err := buf.WriteTo(w)
162162
return err
@@ -196,3 +196,33 @@ type byName []*cobra.Command
196196
func (s byName) Len() int { return len(s) }
197197
func (s byName) Swap(i, j int) { s[i], s[j] = s[j], s[i] }
198198
func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }
199+
200+
type GenDocsOptions struct {
201+
exampleFormatter func(buf *bytes.Buffer, cmd *cobra.Command)
202+
timeGetter func() time.Time
203+
}
204+
205+
func newGenDocsOptions(options []GenDocsOption) *GenDocsOptions {
206+
o := &GenDocsOptions{
207+
exampleFormatter: DefaultExampleFormatter,
208+
timeGetter: DefaultTimeGetter,
209+
}
210+
211+
for _, option := range options {
212+
option(o)
213+
}
214+
215+
return o
216+
}
217+
218+
type GenDocsOption = func(options *GenDocsOptions)
219+
220+
func DefaultTimeGetter() time.Time {
221+
return time.Now()
222+
}
223+
224+
func WithCustomTimeGetter(customTimeGetter func() time.Time) func(options *GenDocsOptions) {
225+
return func(options *GenDocsOptions) {
226+
options.timeGetter = customTimeGetter
227+
}
228+
}

‎cobra2snooty_test.go‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@ import (
2121
"path/filepath"
2222
"strings"
2323
"testing"
24+
"time"
2425

26+
"github.com/bradleyjkemp/cupaloy/v2"
2527
"github.com/spf13/cobra"
2628
)
2729

@@ -282,3 +284,84 @@ func TestArgsRegex(t *testing.T) {
282284
}
283285
})
284286
}
287+
288+
// To update snapshots run: UPDATE_SNAPSHOTS=true go test ./...
289+
func TestGenDocsSnapshots(t *testing.T) {
290+
// Test cases
291+
tests := []struct {
292+
name string
293+
cmd *cobra.Command
294+
options []GenDocsOption
295+
}{
296+
{
297+
name: "default_example",
298+
cmd: &cobra.Command{
299+
Use: "default_example",
300+
Long: "Testing example output using the default example formatter",
301+
Example: "example --test -v",
302+
},
303+
options: []GenDocsOption{
304+
WithCustomTimeGetter(func() time.Time {
305+
return time.Date(2025, 3, 5, 17, 0, 0, 0, time.UTC)
306+
}),
307+
},
308+
},
309+
{
310+
name: "custom_formatter_example",
311+
cmd: &cobra.Command{
312+
Use: "custom_example",
313+
Long: "Testing example output using a custom example formatter",
314+
Example: "example --test -v",
315+
},
316+
options: []GenDocsOption{
317+
WithCustomTimeGetter(func() time.Time {
318+
return time.Date(2025, 3, 5, 17, 0, 0, 0, time.UTC)
319+
}),
320+
WithCustomExampleFormatter(func(buf *bytes.Buffer, cmd *cobra.Command) {
321+
_, _ = fmt.Fprintf(buf, "custom example for %s\n", cmd.Use)
322+
_, _ = buf.WriteString(cmd.Example)
323+
}),
324+
},
325+
},
326+
{
327+
name: "custom_formatter_surround_default_example",
328+
cmd: &cobra.Command{
329+
Use: "custom_formatter_surround_default_example",
330+
Long: "Testing example output using a custom example formatter which calls the default formatter",
331+
Example: "example --test -v",
332+
},
333+
options: []GenDocsOption{
334+
WithCustomTimeGetter(func() time.Time {
335+
return time.Date(2025, 3, 5, 17, 0, 0, 0, time.UTC)
336+
}),
337+
WithCustomExampleFormatter(func(buf *bytes.Buffer, cmd *cobra.Command) {
338+
_, _ = buf.WriteString("-- before example --\n")
339+
DefaultExampleFormatter(buf, cmd)
340+
_, _ = buf.WriteString("-- after example --\n")
341+
}),
342+
},
343+
},
344+
}
345+
346+
// Run tests
347+
for _, tt := range tests {
348+
t.Run(tt.name, func(t *testing.T) {
349+
snapshotter := cupaloy.New(cupaloy.SnapshotFileExtension(".txt"))
350+
// Create buffer to capture output
351+
buf := new(bytes.Buffer)
352+
353+
// Execute function
354+
err := GenDocs(tt.cmd, buf, tt.options...)
355+
if err != nil {
356+
t.Fatalf("GenDocs() error = %v", err)
357+
return
358+
}
359+
360+
// Compare with snapshot
361+
err = snapshotter.SnapshotWithName(tt.name, buf.String())
362+
if err != nil {
363+
t.Errorf("Snapshot comparison failed: %v", err)
364+
}
365+
})
366+
}
367+
}

‎examples.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,18 @@ const (
3030
identChar = " "
3131
)
3232

33+
func DefaultExampleFormatter(buf *bytes.Buffer, cmd *cobra.Command) {
34+
if cmd.Example != "" {
35+
printExamples(buf, cmd)
36+
}
37+
}
38+
39+
func WithCustomExampleFormatter(customFormatter func(buf *bytes.Buffer, cmd *cobra.Command)) func(options *GenDocsOptions) {
40+
return func(options *GenDocsOptions) {
41+
options.exampleFormatter = customFormatter
42+
}
43+
}
44+
3345
func printExamples(buf *bytes.Buffer, cmd *cobra.Command) {
3446
// Create example substrings
3547
examplestrimmed := strings.TrimLeft(cmd.Example, " #")

‎go.mod‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,13 @@ module github.com/mongodb-labs/cobra2snooty
33
go 1.20
44

55
require (
6+
github.com/bradleyjkemp/cupaloy/v2 v2.8.0
67
github.com/spf13/cobra v1.9.1
78
github.com/spf13/pflag v1.0.6
89
)
910

10-
require github.com/inconshreveable/mousetrap v1.1.0 // indirect
11+
require (
12+
github.com/davecgh/go-spew v1.1.1 // indirect
13+
github.com/inconshreveable/mousetrap v1.1.0 // indirect
14+
github.com/pmezard/go-difflib v1.0.0 // indirect
15+
)

‎go.sum‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,21 @@
1+
github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M=
2+
github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0=
13
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
4+
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
5+
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
6+
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
27
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
38
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
9+
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
10+
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
411
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
512
github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
613
github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
714
github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
815
github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
16+
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
17+
github.com/stretchr/objx v0.1.1/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
18+
github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
919
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
20+
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
1021
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

0 commit comments

Comments
 (0)