From 259efbfb887da19ab8e9f976a4e5cefdf4d89c94 Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Fri, 15 Sep 2023 15:01:33 -0400 Subject: [PATCH 01/11] Added all needed pieces to build feature. --- cmd/provenanced/cmd/docgen.go | 47 ++++++++++++++++++++++++++++++ cmd/provenanced/cmd/docgen_test.go | 1 + cmd/provenanced/cmd/root.go | 1 + go.mod | 2 ++ go.sum | 2 ++ 5 files changed, 53 insertions(+) create mode 100644 cmd/provenanced/cmd/docgen.go create mode 100644 cmd/provenanced/cmd/docgen_test.go diff --git a/cmd/provenanced/cmd/docgen.go b/cmd/provenanced/cmd/docgen.go new file mode 100644 index 0000000000..c08bb7de03 --- /dev/null +++ b/cmd/provenanced/cmd/docgen.go @@ -0,0 +1,47 @@ +package cmd + +import ( + "fmt" + + "github.com/cosmos/cosmos-sdk/version" + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +var docGenCmdStart = fmt.Sprintf("%s docgen", version.AppName) + +const ( + FlagMarkdown = "markdown" + FlagYaml = "yaml" + FlagRest = "rest" + FlagManpage = "manpage" +) + +func GetDocGenCmd() *cobra.Command { + cmd := &cobra.Command{ + Use: "docgen", + Short: "Generates cli documentation for the Provenance Blockchain.", + Long: "", + Example: fmt.Sprintf("%s '/tmp' --yaml --markdown", docGenCmdStart), + Hidden: true, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + markdown, err := cmd.Flags().GetBool(FlagMarkdown) + if err != nil { + return err + } + if markdown { + doc.GenMarkdownTree(cmd.Root(), args[0]) + } + + return nil + }, + } + + cmd.Flags().Bool(FlagMarkdown, false, "Generate documentation in the format of markdown pages.") + cmd.Flags().Bool(FlagYaml, false, "Generate documentation in the format of yaml.") + cmd.Flags().Bool(FlagRest, false, "Generate documentation in the format of rest.") + cmd.Flags().Bool(FlagManpage, false, "Generate documentation in the format of manpages.") + + return cmd +} diff --git a/cmd/provenanced/cmd/docgen_test.go b/cmd/provenanced/cmd/docgen_test.go new file mode 100644 index 0000000000..fedae39ac2 --- /dev/null +++ b/cmd/provenanced/cmd/docgen_test.go @@ -0,0 +1 @@ +package cmd_test diff --git a/cmd/provenanced/cmd/root.go b/cmd/provenanced/cmd/root.go index d85cf9ad07..da030bcbdb 100644 --- a/cmd/provenanced/cmd/root.go +++ b/cmd/provenanced/cmd/root.go @@ -154,6 +154,7 @@ func initRootCmd(rootCmd *cobra.Command, encodingConfig params.EncodingConfig) { AddMetaAddressCmd(), snapshot.Cmd(newApp), GetPreUpgradeCmd(), + GetDocGenCmd(), ) fixDebugPubkeyRawTypeFlag(rootCmd) diff --git a/go.mod b/go.mod index f767d38067..7c14fe4152 100644 --- a/go.mod +++ b/go.mod @@ -68,6 +68,7 @@ require ( github.com/cosmos/gorocksdb v1.2.0 // indirect github.com/cosmos/iavl v0.19.6 // indirect github.com/cosmos/ledger-cosmos-go v0.12.2 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect github.com/creachadair/taskgroup v0.3.2 // indirect github.com/danieljoos/wincred v1.1.2 // indirect github.com/davecgh/go-spew v1.1.1 // indirect @@ -144,6 +145,7 @@ require ( github.com/prometheus/procfs v0.9.0 // indirect github.com/rcrowley/go-metrics v0.0.0-20201227073835-cf1acfcdf475 // indirect github.com/rs/cors v1.8.2 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/sasha-s/go-deadlock v0.3.1 // indirect github.com/spf13/afero v1.9.5 // indirect github.com/spf13/jwalterweatherman v1.1.0 // indirect diff --git a/go.sum b/go.sum index 0e0347725c..4c11921fb2 100644 --- a/go.sum +++ b/go.sum @@ -383,6 +383,7 @@ github.com/cosmos/ledger-cosmos-go v0.12.2 h1:/XYaBlE2BJxtvpkHiBm97gFGSGmYGKunKy github.com/cosmos/ledger-cosmos-go v0.12.2/go.mod h1:ZcqYgnfNJ6lAXe4HPtWgarNEY+B74i+2/8MhZw4ziiI= github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE= github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU= +github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w= github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/creachadair/taskgroup v0.3.2 h1:zlfutDS+5XG40AOxcHDSThxKzns8Tnr9jnr6VqkYlkM= github.com/creachadair/taskgroup v0.3.2/go.mod h1:wieWwecHVzsidg2CsUnFinW1faVN4+kq+TDlRJQ0Wbk= @@ -1032,6 +1033,7 @@ github.com/rs/zerolog v1.30.0 h1:SymVODrcRsaRaSInD9yQtKbtWqwsfoPcRff/oRXLj4c= github.com/rs/zerolog v1.30.0/go.mod h1:/tk+P47gFdPXq4QYjvCmT5/Gsug2nagsFWBWhAiSi1w= github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g= github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts= github.com/samuel/go-zookeeper v0.0.0-20190923202752-2cc03de413da/go.mod h1:gi+0XIa01GRL2eRQVjQkKGqKF3SF9vZR/HnPullcV2E= From 07877ab137c5ca8f27765ffd39a6467b3033d690 Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Fri, 15 Sep 2023 15:56:31 -0400 Subject: [PATCH 02/11] Added additional logic. --- cmd/provenanced/cmd/docgen.go | 42 ++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/cmd/provenanced/cmd/docgen.go b/cmd/provenanced/cmd/docgen.go index c08bb7de03..a30b01c5df 100644 --- a/cmd/provenanced/cmd/docgen.go +++ b/cmd/provenanced/cmd/docgen.go @@ -2,6 +2,7 @@ package cmd import ( "fmt" + "os" "github.com/cosmos/cosmos-sdk/version" "github.com/spf13/cobra" @@ -26,12 +27,46 @@ func GetDocGenCmd() *cobra.Command { Hidden: true, Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { + dir := args[0] + if !exists(dir) { + err := os.Mkdir(dir, 0755) + if err != nil { + return err + } + } + + // Check if at least one flag is enabled + markdown, err := cmd.Flags().GetBool(FlagMarkdown) if err != nil { return err } if markdown { - doc.GenMarkdownTree(cmd.Root(), args[0]) + doc.GenMarkdownTree(cmd.Root(), dir) + } + + yaml, err := cmd.Flags().GetBool(FlagYaml) + if err != nil { + return err + } + if yaml { + doc.GenYamlTree(cmd.Root(), dir) + } + + rest, err := cmd.Flags().GetBool(FlagRest) + if err != nil { + return err + } + if rest { + doc.GenReSTTree(cmd.Root(), dir) + } + + manpage, err := cmd.Flags().GetBool(FlagManpage) + if err != nil { + return err + } + if manpage { + doc.GenManTree(cmd.Root(), nil, dir) } return nil @@ -45,3 +80,8 @@ func GetDocGenCmd() *cobra.Command { return cmd } + +func exists(dir string) bool { + _, err := os.Stat(dir) + return err == nil +} From cc48f795896d59aa35e43d624cc3c79753202a9d Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Mon, 18 Sep 2023 14:04:00 -0400 Subject: [PATCH 03/11] Update usage and long help for command. --- cmd/provenanced/cmd/docgen.go | 67 +++++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 26 deletions(-) diff --git a/cmd/provenanced/cmd/docgen.go b/cmd/provenanced/cmd/docgen.go index a30b01c5df..ae754bcf01 100644 --- a/cmd/provenanced/cmd/docgen.go +++ b/cmd/provenanced/cmd/docgen.go @@ -20,53 +20,68 @@ const ( func GetDocGenCmd() *cobra.Command { cmd := &cobra.Command{ - Use: "docgen", - Short: "Generates cli documentation for the Provenance Blockchain.", - Long: "", + Use: "docgen (--markdown) (--yaml) (--rest) (--manpages) [flags]", + Short: "Generates cli documentation for the Provenance Blockchain.", + Long: `Generates cli documentation for the Provenance Blockchain. +Various documentation formats can be generated, including markdown, YAML, REST, and man pages. +To ensure the command's success, you must specify at least one format. +A successful command will not only generate files in the selected formats but also create the target directory if it doesn't already exist.`, Example: fmt.Sprintf("%s '/tmp' --yaml --markdown", docGenCmdStart), Hidden: true, Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - dir := args[0] - if !exists(dir) { - err := os.Mkdir(dir, 0755) - if err != nil { - return err - } - } - - // Check if at least one flag is enabled - markdown, err := cmd.Flags().GetBool(FlagMarkdown) if err != nil { return err } - if markdown { - doc.GenMarkdownTree(cmd.Root(), dir) - } - yaml, err := cmd.Flags().GetBool(FlagYaml) if err != nil { return err } - if yaml { - doc.GenYamlTree(cmd.Root(), dir) - } - rest, err := cmd.Flags().GetBool(FlagRest) if err != nil { return err } - if rest { - doc.GenReSTTree(cmd.Root(), dir) - } - manpage, err := cmd.Flags().GetBool(FlagManpage) if err != nil { return err } + + if !markdown && !yaml && !rest && !manpage { + return fmt.Errorf("at least one doc type must be specified.") + } + + dir := args[0] + if !exists(dir) { + err := os.Mkdir(dir, 0755) + if err != nil { + return err + } + } + + if markdown { + err = doc.GenMarkdownTree(cmd.Root(), dir) + if err != nil { + return err + } + } + if yaml { + err = doc.GenYamlTree(cmd.Root(), dir) + if err != nil { + return err + } + } + if rest { + err = doc.GenReSTTree(cmd.Root(), dir) + if err != nil { + return err + } + } if manpage { - doc.GenManTree(cmd.Root(), nil, dir) + err = doc.GenManTree(cmd.Root(), nil, dir) + if err != nil { + return err + } } return nil From 8beeafb9d1c47a6ef56086a13414f65c826e18d9 Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Mon, 18 Sep 2023 16:43:57 -0400 Subject: [PATCH 04/11] Add tests for docgen, but still need to verify generated contents. --- cmd/provenanced/cmd/docgen_test.go | 118 +++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/cmd/provenanced/cmd/docgen_test.go b/cmd/provenanced/cmd/docgen_test.go index fedae39ac2..55b839a751 100644 --- a/cmd/provenanced/cmd/docgen_test.go +++ b/cmd/provenanced/cmd/docgen_test.go @@ -1 +1,119 @@ package cmd_test + +import ( + "context" + "os" + "path/filepath" + "testing" + + "github.com/cosmos/cosmos-sdk/client" + "github.com/cosmos/cosmos-sdk/server" + sdksim "github.com/cosmos/cosmos-sdk/simapp" + genutiltest "github.com/cosmos/cosmos-sdk/x/genutil/client/testutil" + provenancecmd "github.com/provenance-io/provenance/cmd/provenanced/cmd" + "github.com/spf13/viper" + "github.com/stretchr/testify/require" + "github.com/tendermint/tendermint/libs/log" +) + +func TestDocGen(t *testing.T) { + tests := []struct { + name string + target string + createTarget bool + flags []string + err string + }{ + { + name: "failure - no flags specified", + target: "tmp", + createTarget: true, + err: "at least one doc type must be specified.", + }, + { + name: "failure - unsupported flag format", + target: "tmp", + flags: []string{"--bad"}, + createTarget: true, + err: "unknown flag: --bad", + }, + { + name: "success - yaml is generated", + target: "tmp", + createTarget: true, + flags: []string{"--yaml"}, + }, + { + name: "success - rest is generated", + target: "tmp", + createTarget: true, + flags: []string{"--rest"}, + }, + { + name: "success - manpage is generated", + target: "tmp", + createTarget: true, + flags: []string{"--manpage"}, + }, + { + name: "success - markdown is generated", + target: "tmp", + createTarget: true, + flags: []string{"--markdown"}, + }, + { + name: "success - multiple types supported", + target: "tmp", + createTarget: true, + flags: []string{"--markdown", "--yaml"}, + }, + { + name: "success - generates a new directory", + target: "tmp2", + createTarget: false, + flags: []string{"--yaml"}, + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + home := t.TempDir() + + targetPath := filepath.Join(home, tc.target) + if tc.createTarget { + require.NoError(t, os.Mkdir(targetPath, 0755)) + } + + logger := log.NewNopLogger() + cfg, err := genutiltest.CreateDefaultTendermintConfig(home) + require.NoError(t, err) + + appCodec := sdksim.MakeTestEncodingConfig().Codec + err = genutiltest.ExecInitCmd(testMbm, home, appCodec) + require.NoError(t, err) + + serverCtx := server.NewContext(viper.New(), cfg, logger) + clientCtx := client.Context{}.WithCodec(appCodec).WithHomeDir(home) + + ctx := context.Background() + ctx = context.WithValue(ctx, client.ClientContextKey, &clientCtx) + ctx = context.WithValue(ctx, server.ServerContextKey, serverCtx) + + cmd := provenancecmd.GetDocGenCmd() + args := append([]string{targetPath}, tc.flags...) + cmd.SetArgs(args) + + if len(tc.err) > 0 { + err := cmd.ExecuteContext(ctx) + require.Error(t, err) + require.Equal(t, tc.err, err.Error()) + } else { + err := cmd.ExecuteContext(ctx) + require.NoError(t, err) + // We probably want to check generation of files + } + + require.NoError(t, os.RemoveAll(targetPath)) + }) + } +} From fdd8e850debf11959fc2f9121053fe9dfd49a3c7 Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Mon, 18 Sep 2023 17:10:53 -0400 Subject: [PATCH 05/11] Finish tests for docgen command. --- cmd/provenanced/cmd/docgen_test.go | 39 ++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/cmd/provenanced/cmd/docgen_test.go b/cmd/provenanced/cmd/docgen_test.go index 55b839a751..053d992359 100644 --- a/cmd/provenanced/cmd/docgen_test.go +++ b/cmd/provenanced/cmd/docgen_test.go @@ -23,6 +23,7 @@ func TestDocGen(t *testing.T) { createTarget bool flags []string err string + extensions []string }{ { name: "failure - no flags specified", @@ -42,36 +43,42 @@ func TestDocGen(t *testing.T) { target: "tmp", createTarget: true, flags: []string{"--yaml"}, + extensions: []string{".yaml"}, }, { name: "success - rest is generated", target: "tmp", createTarget: true, flags: []string{"--rest"}, + extensions: []string{".rst"}, }, { name: "success - manpage is generated", target: "tmp", createTarget: true, flags: []string{"--manpage"}, + extensions: []string{".1"}, }, { name: "success - markdown is generated", target: "tmp", createTarget: true, flags: []string{"--markdown"}, + extensions: []string{".md"}, }, { name: "success - multiple types supported", target: "tmp", createTarget: true, flags: []string{"--markdown", "--yaml"}, + extensions: []string{".md", ".yaml"}, }, { name: "success - generates a new directory", target: "tmp2", createTarget: false, flags: []string{"--yaml"}, + extensions: []string{".md", ".yaml"}, }, } @@ -81,16 +88,16 @@ func TestDocGen(t *testing.T) { targetPath := filepath.Join(home, tc.target) if tc.createTarget { - require.NoError(t, os.Mkdir(targetPath, 0755)) + require.NoError(t, os.Mkdir(targetPath, 0755), "Mkdir successfully created directory") } logger := log.NewNopLogger() cfg, err := genutiltest.CreateDefaultTendermintConfig(home) - require.NoError(t, err) + require.NoError(t, err, "Created default tendermint config") appCodec := sdksim.MakeTestEncodingConfig().Codec err = genutiltest.ExecInitCmd(testMbm, home, appCodec) - require.NoError(t, err) + require.NoError(t, err, "Executed init command") serverCtx := server.NewContext(viper.New(), cfg, logger) clientCtx := client.Context{}.WithCodec(appCodec).WithHomeDir(home) @@ -105,15 +112,31 @@ func TestDocGen(t *testing.T) { if len(tc.err) > 0 { err := cmd.ExecuteContext(ctx) - require.Error(t, err) - require.Equal(t, tc.err, err.Error()) + require.Error(t, err, "should throw an error") + require.Equal(t, tc.err, err.Error(), "should return the correct error") + files, err := os.ReadDir(targetPath) + require.NoError(t, err, "ReadDir should not return an error") + require.Equal(t, 0, len(files), "should not generate files when failed") } else { err := cmd.ExecuteContext(ctx) - require.NoError(t, err) - // We probably want to check generation of files + require.NoError(t, err, "should not return an error") + + files, err := os.ReadDir(targetPath) + require.NoError(t, err, "ReadDir should not return an error") + require.NotZero(t, len(files), "should generate files when successful") + + for _, file := range files { + ext := filepath.Ext(file.Name()) + + contains := false + for _, extension := range tc.extensions { + contains = contains || ext == extension + } + require.True(t, contains, "should generate files with correct extension") + } } - require.NoError(t, os.RemoveAll(targetPath)) + require.NoError(t, os.RemoveAll(targetPath), "RemoveAll should be able to remove the temporary target directory") }) } } From bb4371ab9712d5c571bc68ec5b36511235ae1b9f Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Mon, 18 Sep 2023 17:13:05 -0400 Subject: [PATCH 06/11] Lint code. --- cmd/provenanced/cmd/docgen.go | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/cmd/provenanced/cmd/docgen.go b/cmd/provenanced/cmd/docgen.go index ae754bcf01..ec4465df50 100644 --- a/cmd/provenanced/cmd/docgen.go +++ b/cmd/provenanced/cmd/docgen.go @@ -4,9 +4,10 @@ import ( "fmt" "os" - "github.com/cosmos/cosmos-sdk/version" "github.com/spf13/cobra" "github.com/spf13/cobra/doc" + + "github.com/cosmos/cosmos-sdk/version" ) var docGenCmdStart = fmt.Sprintf("%s docgen", version.AppName) @@ -48,12 +49,12 @@ A successful command will not only generate files in the selected formats but al } if !markdown && !yaml && !rest && !manpage { - return fmt.Errorf("at least one doc type must be specified.") + return fmt.Errorf("at least one doc type must be specified") } dir := args[0] if !exists(dir) { - err := os.Mkdir(dir, 0755) + err = os.Mkdir(dir, 0755) if err != nil { return err } From 034608e8946a1e02e62cdc75a7a8c7c30e4b2b4a Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Mon, 18 Sep 2023 17:14:27 -0400 Subject: [PATCH 07/11] Changelog entry. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index be724b0a83..a655b08b67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ Management of holds is internal, but there are queries for looking up holds on accounts. Holds are also reflected in the `x/bank` module's `SpendableBalances` query. * Add new MaxSupply param to marker module and deprecate MaxTotalSupply. [#1292](https://github.com/provenance-io/provenance/issues/1292). +* Add hidden docgen command to output documentation in different formats. [#1468](https://github.com/provenance-io/provenance/issues/1468). ### Improvements From 737221fdf6430f1aa13c0f6f8c29525e917cd7c2 Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Mon, 18 Sep 2023 19:26:50 -0400 Subject: [PATCH 08/11] Fix typo in test. --- cmd/provenanced/cmd/docgen_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/provenanced/cmd/docgen_test.go b/cmd/provenanced/cmd/docgen_test.go index 053d992359..f56aacc0b2 100644 --- a/cmd/provenanced/cmd/docgen_test.go +++ b/cmd/provenanced/cmd/docgen_test.go @@ -29,7 +29,7 @@ func TestDocGen(t *testing.T) { name: "failure - no flags specified", target: "tmp", createTarget: true, - err: "at least one doc type must be specified.", + err: "at least one doc type must be specified", }, { name: "failure - unsupported flag format", From 34aef0a60ba4c5d2513faefad9eb844e08b7d7fc Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Tue, 19 Sep 2023 09:30:27 -0400 Subject: [PATCH 09/11] Add test for invalid target directory. --- cmd/provenanced/cmd/docgen_test.go | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/cmd/provenanced/cmd/docgen_test.go b/cmd/provenanced/cmd/docgen_test.go index f56aacc0b2..120c438c49 100644 --- a/cmd/provenanced/cmd/docgen_test.go +++ b/cmd/provenanced/cmd/docgen_test.go @@ -2,8 +2,10 @@ package cmd_test import ( "context" + "fmt" "os" "path/filepath" + "strings" "testing" "github.com/cosmos/cosmos-sdk/client" @@ -38,6 +40,13 @@ func TestDocGen(t *testing.T) { createTarget: true, err: "unknown flag: --bad", }, + { + name: "failure - invalid target directory", + target: "/tmp/tmp2/tmp3", + flags: []string{"--yaml"}, + createTarget: false, + err: "mkdir %s: no such file or directory", + }, { name: "success - yaml is generated", target: "tmp", @@ -113,10 +122,15 @@ func TestDocGen(t *testing.T) { if len(tc.err) > 0 { err := cmd.ExecuteContext(ctx) require.Error(t, err, "should throw an error") - require.Equal(t, tc.err, err.Error(), "should return the correct error") + expected := tc.err + if strings.Contains(expected, "%s") { + expected = fmt.Sprintf(expected, targetPath) + } + require.Equal(t, expected, err.Error(), "should return the correct error") files, err := os.ReadDir(targetPath) - require.NoError(t, err, "ReadDir should not return an error") - require.Equal(t, 0, len(files), "should not generate files when failed") + if err != nil { + require.Equal(t, 0, len(files), "should not generate files when failed") + } } else { err := cmd.ExecuteContext(ctx) require.NoError(t, err, "should not return an error") @@ -136,7 +150,9 @@ func TestDocGen(t *testing.T) { } } - require.NoError(t, os.RemoveAll(targetPath), "RemoveAll should be able to remove the temporary target directory") + if _, err := os.Stat(targetPath); err != nil { + require.NoError(t, os.RemoveAll(targetPath), "RemoveAll should be able to remove the temporary target directory") + } }) } } From b84755875aa04fa2ac5cdb651434d6af267520c4 Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Tue, 19 Sep 2023 09:56:28 -0400 Subject: [PATCH 10/11] Add tests for invalid flag values. --- cmd/provenanced/cmd/docgen_test.go | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/cmd/provenanced/cmd/docgen_test.go b/cmd/provenanced/cmd/docgen_test.go index 120c438c49..719612581b 100644 --- a/cmd/provenanced/cmd/docgen_test.go +++ b/cmd/provenanced/cmd/docgen_test.go @@ -47,6 +47,34 @@ func TestDocGen(t *testing.T) { createTarget: false, err: "mkdir %s: no such file or directory", }, + { + name: "failure - bad yaml value", + target: "tmp", + createTarget: true, + flags: []string{"--yaml=xyz"}, + err: "invalid argument \"xyz\" for \"--yaml\" flag: strconv.ParseBool: parsing \"xyz\": invalid syntax", + }, + { + name: "failure - bad rest value", + target: "tmp", + createTarget: true, + flags: []string{"--rest=xyz"}, + err: "invalid argument \"xyz\" for \"--rest\" flag: strconv.ParseBool: parsing \"xyz\": invalid syntax", + }, + { + name: "failure - bad markdown value", + target: "tmp", + createTarget: true, + flags: []string{"--markdown=xyz"}, + err: "invalid argument \"xyz\" for \"--markdown\" flag: strconv.ParseBool: parsing \"xyz\": invalid syntax", + }, + { + name: "failure - bad manpage value", + target: "tmp", + createTarget: true, + flags: []string{"--manpage=xyz"}, + err: "invalid argument \"xyz\" for \"--manpage\" flag: strconv.ParseBool: parsing \"xyz\": invalid syntax", + }, { name: "success - yaml is generated", target: "tmp", From e4d1a9fb526af0cef40b54e298fc2ee5e3a5d254 Mon Sep 17 00:00:00 2001 From: Matthew Witkowski Date: Wed, 20 Sep 2023 12:30:10 -0400 Subject: [PATCH 11/11] Rename rest to rst to improve clarity. --- cmd/provenanced/cmd/docgen.go | 14 +++++++------- cmd/provenanced/cmd/docgen_test.go | 10 +++++----- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/cmd/provenanced/cmd/docgen.go b/cmd/provenanced/cmd/docgen.go index ec4465df50..f59b6e1ea1 100644 --- a/cmd/provenanced/cmd/docgen.go +++ b/cmd/provenanced/cmd/docgen.go @@ -15,16 +15,16 @@ var docGenCmdStart = fmt.Sprintf("%s docgen", version.AppName) const ( FlagMarkdown = "markdown" FlagYaml = "yaml" - FlagRest = "rest" + FlagRst = "rst" FlagManpage = "manpage" ) func GetDocGenCmd() *cobra.Command { cmd := &cobra.Command{ - Use: "docgen (--markdown) (--yaml) (--rest) (--manpages) [flags]", + Use: "docgen (--markdown) (--yaml) (--rst) (--manpages) [flags]", Short: "Generates cli documentation for the Provenance Blockchain.", Long: `Generates cli documentation for the Provenance Blockchain. -Various documentation formats can be generated, including markdown, YAML, REST, and man pages. +Various documentation formats can be generated, including markdown, YAML, RST, and man pages. To ensure the command's success, you must specify at least one format. A successful command will not only generate files in the selected formats but also create the target directory if it doesn't already exist.`, Example: fmt.Sprintf("%s '/tmp' --yaml --markdown", docGenCmdStart), @@ -39,7 +39,7 @@ A successful command will not only generate files in the selected formats but al if err != nil { return err } - rest, err := cmd.Flags().GetBool(FlagRest) + rst, err := cmd.Flags().GetBool(FlagRst) if err != nil { return err } @@ -48,7 +48,7 @@ A successful command will not only generate files in the selected formats but al return err } - if !markdown && !yaml && !rest && !manpage { + if !markdown && !yaml && !rst && !manpage { return fmt.Errorf("at least one doc type must be specified") } @@ -72,7 +72,7 @@ A successful command will not only generate files in the selected formats but al return err } } - if rest { + if rst { err = doc.GenReSTTree(cmd.Root(), dir) if err != nil { return err @@ -91,7 +91,7 @@ A successful command will not only generate files in the selected formats but al cmd.Flags().Bool(FlagMarkdown, false, "Generate documentation in the format of markdown pages.") cmd.Flags().Bool(FlagYaml, false, "Generate documentation in the format of yaml.") - cmd.Flags().Bool(FlagRest, false, "Generate documentation in the format of rest.") + cmd.Flags().Bool(FlagRst, false, "Generate documentation in the format of rst.") cmd.Flags().Bool(FlagManpage, false, "Generate documentation in the format of manpages.") return cmd diff --git a/cmd/provenanced/cmd/docgen_test.go b/cmd/provenanced/cmd/docgen_test.go index 719612581b..9b92feda7e 100644 --- a/cmd/provenanced/cmd/docgen_test.go +++ b/cmd/provenanced/cmd/docgen_test.go @@ -55,11 +55,11 @@ func TestDocGen(t *testing.T) { err: "invalid argument \"xyz\" for \"--yaml\" flag: strconv.ParseBool: parsing \"xyz\": invalid syntax", }, { - name: "failure - bad rest value", + name: "failure - bad rst value", target: "tmp", createTarget: true, - flags: []string{"--rest=xyz"}, - err: "invalid argument \"xyz\" for \"--rest\" flag: strconv.ParseBool: parsing \"xyz\": invalid syntax", + flags: []string{"--rst=xyz"}, + err: "invalid argument \"xyz\" for \"--rst\" flag: strconv.ParseBool: parsing \"xyz\": invalid syntax", }, { name: "failure - bad markdown value", @@ -83,10 +83,10 @@ func TestDocGen(t *testing.T) { extensions: []string{".yaml"}, }, { - name: "success - rest is generated", + name: "success - rst is generated", target: "tmp", createTarget: true, - flags: []string{"--rest"}, + flags: []string{"--rst"}, extensions: []string{".rst"}, }, {