Skip to content

Commit

Permalink
Update docs structure and content (#94)
Browse files Browse the repository at this point in the history 
* start applying new docs structure

* mark attest command as beta and audit trail commands as deprecated

* rename notifications to actions

* add links to github and gitlab examples

* add k8s and aws envs reporting tutorials

* more content updates. kosli-dev/server#1251

* update expected server error messages in tests

* update ecs snapshot expected output
  • Loading branch information
@sami-alajrami
sami-alajrami authored Jan 23, 2024
1 parent 7428310 commit d5fbc95
Show file tree
Hide file tree
Showing 49 changed files with 1,036 additions and 1,225 deletions.
7 changes: 4 additions & 3 deletions cmd/kosli/attest.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,10 @@ const attestDesc = `All Kosli attest commands.`

func newAttestCmd(out io.Writer) *cobra.Command {
cmd := &cobra.Command{
Use: "attest",
Short: attestDesc,
Long: attestDesc,
Use: "attest",
Short: attestDesc,
Long: attestDesc,
Annotations: map[string]string{"betaCLI": "true"},
}

// Add subcommands
Expand Down
11 changes: 6 additions & 5 deletions cmd/kosli/beginTrail.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,12 @@ type TrailPayload struct {
func newBeginTrailCmd(out io.Writer) *cobra.Command {
o := new(beginTrailOptions)
cmd := &cobra.Command{
Use: "trail TRAIL-NAME",
Short: beginTrailShortDesc,
Long: beginTrailShortDesc,
Example: beginTrailExample,
Args: cobra.MaximumNArgs(1),
Use: "trail TRAIL-NAME",
Short: beginTrailShortDesc,
Long: beginTrailShortDesc,
Example: beginTrailExample,
Args: cobra.MaximumNArgs(1),
Annotations: map[string]string{"betaCLI": "true"},
PreRunE: func(cmd *cobra.Command, args []string) error {
err := RequireGlobalFlags(global, []string{"Org", "ApiToken"})
if err != nil {
Expand Down
12 changes: 6 additions & 6 deletions cmd/kosli/createAuditTrail.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,12 +36,12 @@ type AuditTrailPayload struct {
func newCreateAuditTrailCmd(out io.Writer) *cobra.Command {
o := new(createAuditTrailOptions)
cmd := &cobra.Command{
Use: "audit-trail AUDIT-TRAIL-NAME",
Short: createAuditTrailShortDesc,
Long: createAuditTrailLongDesc,
Example: createAuditTrailExample,
Annotations: map[string]string{"betaCLI": "true"},
Args: cobra.MaximumNArgs(1),
Use: "audit-trail AUDIT-TRAIL-NAME",
Short: createAuditTrailShortDesc,
Long: createAuditTrailLongDesc,
Example: createAuditTrailExample,
Deprecated: "Audit trails are deprecated. Please use Flows and Trail instead.",
Args: cobra.MaximumNArgs(1),
PreRunE: func(cmd *cobra.Command, args []string) error {
err := RequireGlobalFlags(global, []string{"Org", "ApiToken"})
if err != nil {
Expand Down
26 changes: 8 additions & 18 deletions cmd/kosli/createAuditTrail_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,53 +30,43 @@ func (suite *CreateAuditTrailCommandTestSuite) TestCreateAuditTrailCmd() {
wantError: true,
name: "fails when more arguments are provided",
cmd: "create audit-trail newAuditTrail xxx" + suite.defaultKosliArguments,
golden: "Error: accepts at most 1 arg(s), received 2\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: accepts at most 1 arg(s), received 2\n",
},
{
wantError: true,
name: "fails when name is considered invalid by the server",
cmd: "create audit-trail foo_bar --steps step1,step2" + suite.defaultKosliArguments,
golden: "Error: Input payload validation failed: map[name:'foo_bar' does not match '^[a-zA-Z0-9\\\\-]+$']\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: Input payload validation failed: map[name:'foo_bar' does not match '^[a-zA-Z0-9\\\\-]+$']\n",
},
// {
// name: "can create an audit trail",
// cmd: "create audit-trail newAuditTrail --description \"my new audit trail\" --steps step1,step2" + suite.defaultKosliArguments,
// golden: "audit trail 'newAuditTrail' was created\n",
// },
{
wantError: true,
name: "can create an audit trail",
name: "cannot create an audit trail when it is not enabled for you",
cmd: "create audit-trail newAuditTrail --description \"my new audit trail\" --steps step1,step2" + suite.defaultKosliArguments,
golden: "Error: The audit trail feature is in beta. You can enable the feature by running the following Kosli CLI command (version 2.3.2 or later):\n$ kosli enable beta\nJoin our Slack community for more information: https://www.kosli.com/community/\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: You don't have access to the audit trails feature. This feature has been deprecated in favour of Flows and Trails.\n",
},
// {
// name: "re-creating a flow updates its metadata",
// cmd: "create audit-trail newAuditTrail --description \"changed description\" --steps step1,step2" + suite.defaultKosliArguments,
// golden: "audit trail 'newAuditTrail' was created\n",
// },
{
wantError: true,
name: "re-creating a flow updates its metadata",
cmd: "create audit-trail newAuditTrail --description \"changed description\" --steps step1,step2" + suite.defaultKosliArguments,
golden: "Error: The audit trail feature is in beta. You can enable the feature by running the following Kosli CLI command (version 2.3.2 or later):\n$ kosli enable beta\nJoin our Slack community for more information: https://www.kosli.com/community/\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: You don't have access to the audit trails feature. This feature has been deprecated in favour of Flows and Trails.\n",
},
{
wantError: true,
name: "missing --org flag causes an error",
cmd: "create audit-trail newAuditTrail --description \"my new audit trail\" --steps step1,step2 -H http://localhost:8001 -a eyJhbGciOiJIUzUxMiIsImlhdCI6MTYyNTY0NDUwMCwiZXhwIjoxNjI1NjQ4MTAwfQ.eyJpZCI6IjgzYTBkY2Q1In0.1B-xDlajF46vipL49zPbnXBRgotqGGcB3lxwpJxZ3HNce07E0p2LwO7UDYve9j2G9fQtKrKhUKvVR97SQOEFLQ",
golden: "Error: --org is not set\nUsage: kosli create audit-trail AUDIT-TRAIL-NAME [flags]\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: --org is not set\nUsage: kosli create audit-trail AUDIT-TRAIL-NAME [flags]\n",
},
{
wantError: true,
name: "missing --api-token flag causes an error",
cmd: "create audit-trail newAuditTrail --description \"my new audit trail\" --steps step1,step2 --org cyber-dojo -H http://localhost:8001",
golden: "Error: --api-token is not set\nUsage: kosli create audit-trail AUDIT-TRAIL-NAME [flags]\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: --api-token is not set\nUsage: kosli create audit-trail AUDIT-TRAIL-NAME [flags]\n",
},
{
wantError: true,
name: "missing name argument fails",
cmd: "create audit-trail --description \"my new flow\" --steps step1,step2" + suite.defaultKosliArguments,
golden: "Error: audit trail name must be provided as an argument\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: audit trail name must be provided as an argument\n",
},
}

Expand Down
27 changes: 18 additions & 9 deletions cmd/kosli/docs.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,21 +54,22 @@ func (o *docsOptions) run() error {
return "/client_reference/" + strings.ToLower(base) + "/"
}

hdrFunc := func(filename string, beta bool) string {
hdrFunc := func(filename string, beta, deprecated bool) string {
base := filepath.Base(filename)
name := strings.TrimSuffix(base, path.Ext(base))
title := strings.ToLower(strings.Replace(name, "_", " ", -1))
return fmt.Sprintf("---\ntitle: \"%s\"\nbeta: %t\n---\n\n", title, beta)
return fmt.Sprintf("---\ntitle: \"%s\"\nbeta: %t\ndeprecated: %t\n---\n\n", title, beta, deprecated)
}

return MereklyGenMarkdownTreeCustom(o.topCmd, o.dest, hdrFunc, linkHandler)
}
return doc.GenMarkdownTree(o.topCmd, o.dest)
}

func MereklyGenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string, bool) string, linkHandler func(string) string) error {
func MereklyGenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string, bool, bool) string, linkHandler func(string) string) error {
for _, c := range cmd.Commands() {
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
// skip all unavailable commands except deprecated ones
if (!c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand()) && c.Deprecated == "" {
continue
}
if err := MereklyGenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
Expand All @@ -85,7 +86,7 @@ func MereklyGenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender
}
defer f.Close()

if _, err := io.WriteString(f, filePrepender(filename, isBeta(cmd))); err != nil {
if _, err := io.WriteString(f, filePrepender(filename, isBeta(cmd), isDeprecated(cmd))); err != nil {
return err
}
if err := KosliGenMarkdownCustom(cmd, f, linkHandler); err != nil {
Expand All @@ -107,11 +108,19 @@ func KosliGenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(st

if isBeta(cmd) {
buf.WriteString("{{< hint warning >}}")
buf.WriteString(fmt.Sprintf("**%s** is a beta feature. \n", name))
buf.WriteString("Beta features provide early access to product functionality. These ")
buf.WriteString("features may change between releases without warning, or can be removed from a ")
buf.WriteString(fmt.Sprintf("**%s** is a beta feature. ", name))
buf.WriteString("Beta features provide early access to product functionality. ")
buf.WriteString("These features may change between releases without warning, or can be removed in a ")
buf.WriteString("future release.\n")
buf.WriteString("You can enable beta features by using the `kosli enable beta` command.")
buf.WriteString("Please contact us to enable this feature for your organization.")
// buf.WriteString("You can enable beta features by using the `kosli enable beta` command.")
buf.WriteString("{{< /hint >}}\n")
}

if isDeprecated(cmd) {
buf.WriteString("{{< hint danger >}}")
buf.WriteString(fmt.Sprintf("**%s** is a deprecated. %s ", name, cmd.Deprecated))
buf.WriteString("Deprecated commands will be removed in a future release.")
buf.WriteString("{{< /hint >}}\n")
}

Expand Down
10 changes: 5 additions & 5 deletions cmd/kosli/getAuditTrail.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ type getAuditTrailsOptions struct {
func newGetAuditTrailCmd(out io.Writer) *cobra.Command {
o := new(getAuditTrailsOptions)
cmd := &cobra.Command{
Use: "audit-trail AUDIT-TRAIL-NAME",
Short: getAuditTrailDesc,
Long: getAuditTrailDesc,
Annotations: map[string]string{"betaCLI": "true"},
Args: cobra.ExactArgs(1),
Use: "audit-trail AUDIT-TRAIL-NAME",
Short: getAuditTrailDesc,
Long: getAuditTrailDesc,
Args: cobra.ExactArgs(1),
Deprecated: "Audit trails are deprecated. Please use Flows and Trail instead.",
PreRunE: func(cmd *cobra.Command, args []string) error {
err := RequireGlobalFlags(global, []string{"Org", "ApiToken"})
if err != nil {
Expand Down
21 changes: 3 additions & 18 deletions cmd/kosli/getAuditTrail_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,39 +30,24 @@ func (suite *GetAuditTrailCommandTestSuite) SetupTest() {

func (suite *GetAuditTrailCommandTestSuite) TestGetAuditTrailCmd() {
tests := []cmdTestCase{
// {
// wantError: true,
// name: "getting a non existing audit trail fails",
// cmd: fmt.Sprintf(`get audit-trail non-existing %s`, suite.defaultKosliArguments),
// golden: "Error: Audit Trail called 'non-existing' does not exist for organization 'audit-trail-get-org'\n",
// },
{
wantError: true,
name: "getting a non existing audit trail fails",
cmd: fmt.Sprintf(`get audit-trail non-existing %s`, suite.defaultKosliArguments),
golden: "Error: The audit trail feature is in beta. You can enable the feature by running the following Kosli CLI command (version 2.3.2 or later):\n$ kosli enable beta\nJoin our Slack community for more information: https://www.kosli.com/community/\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: You don't have access to the audit trails feature. This feature has been deprecated in favour of Flows and Trails.\n",
},
{
wantError: true,
name: "providing more than one argument fails",
cmd: fmt.Sprintf(`get audit-trail non-existing xxx %s`, suite.defaultKosliArguments),
golden: "Error: accepts 1 arg(s), received 2\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: accepts 1 arg(s), received 2\n",
},
// {
// name: "getting an existing audit trail works",
// cmd: fmt.Sprintf(`get audit-trail %s %s`, suite.auditTrailName, suite.defaultKosliArguments),
// goldenFile: "output/get/get-audit-trail.txt",
// },
{
wantError: true,
name: "getting an existing audit trail works",
cmd: fmt.Sprintf(`get audit-trail %s %s`, suite.auditTrailName, suite.defaultKosliArguments),
golden: "Error: The audit trail feature is in beta. You can enable the feature by running the following Kosli CLI command (version 2.3.2 or later):\n$ kosli enable beta\nJoin our Slack community for more information: https://www.kosli.com/community/\n",
golden: "Command \"audit-trail\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: You don't have access to the audit trails feature. This feature has been deprecated in favour of Flows and Trails.\n",
},
// {
// name: "getting an existing audit trail with --output json works",
// cmd: fmt.Sprintf(`get audit-trail %s --output json %s`, suite.auditTrailName, suite.defaultKosliArguments),
// },
}

runTestCmd(suite.T(), tests)
Expand Down
12 changes: 6 additions & 6 deletions cmd/kosli/getWorkflow.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,12 @@ type getWorkflowOptions struct {
func newGetWorkflowCmd(out io.Writer) *cobra.Command {
o := new(getWorkflowOptions)
cmd := &cobra.Command{
Use: "workflow ID",
Short: getWorkflowShortDesc,
Long: getWorkflowShortDesc,
Example: getWorkflowExample,
Annotations: map[string]string{"betaCLI": "true"},
Args: cobra.ExactArgs(1),
Use: "workflow ID",
Short: getWorkflowShortDesc,
Long: getWorkflowShortDesc,
Example: getWorkflowExample,
Args: cobra.ExactArgs(1),
Deprecated: "Audit trails are deprecated. Please use Flows and Trail instead.",
PreRunE: func(cmd *cobra.Command, args []string) error {
err := RequireGlobalFlags(global, []string{"Org", "ApiToken"})
if err != nil {
Expand Down
26 changes: 1 addition & 25 deletions cmd/kosli/getWorkflow_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,36 +34,12 @@ func (suite *GetWorkflowCommandTestSuite) SetupTest() {

func (suite *GetWorkflowCommandTestSuite) TestGetWorkflowCmd() {
tests := []cmdTestCase{
// {
// name: "get workflow works",
// cmd: fmt.Sprintf(`get workflow %s --audit-trail %s %s`,
// suite.workflowID, suite.auditTrailName, suite.workflowOrgKosliArguments),
// goldenFile: "output/get/get-workflow.txt",
// },
// {
// wantError: true,
// name: "get workflow fails when there is no workflow",
// cmd: fmt.Sprintf(`get workflow non-existing --audit-trail %s %s`, suite.auditTrailName, suite.workflowOrgKosliArguments),
// golden: "Error: Workflow with ID 'non-existing' does not exist for audit trail testGetWorkflow in organization 'get-workflow-org'\n",
// },
{
wantError: true,
name: "get workflow fails when there is no workflow",
cmd: fmt.Sprintf(`get workflow non-existing --audit-trail %s %s`, suite.auditTrailName, suite.workflowOrgKosliArguments),
golden: "Error: The audit trail feature is in beta. You can enable the feature by running the following Kosli CLI command (version 2.3.2 or later):\n$ kosli enable beta\nJoin our Slack community for more information: https://www.kosli.com/community/\n",
golden: "Command \"workflow\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: You don't have access to the audit trails feature. This feature has been deprecated in favour of Flows and Trails.\n",
},
// {
// name: "get workflow works with --output json when there is workflow",
// cmd: fmt.Sprintf(`get workflow %s --audit-trail %s --output json %s`,
// suite.workflowID, suite.auditTrailName, suite.workflowOrgKosliArguments),
// },
// {
// wantError: true,
// name: "get workflow fails with --output json when there is no workflow",
// cmd: fmt.Sprintf(`get workflow non-existing --audit-trail %s --output json %s`,
// suite.auditTrailName, suite.workflowOrgKosliArguments),
// golden: "Error: Workflow with ID 'non-existing' does not exist for audit trail testGetWorkflow in organization 'get-workflow-org'\n",
// },
}

runTestCmd(suite.T(), tests)
Expand Down
10 changes: 5 additions & 5 deletions cmd/kosli/listAuditTrails.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@ type listAuditTrailsOptions struct {
func newListAuditTrailsCmd(out io.Writer) *cobra.Command {
o := new(listAuditTrailsOptions)
cmd := &cobra.Command{
Use: "audit-trails",
Short: listAuditTrailsDesc,
Long: listAuditTrailsDesc,
Annotations: map[string]string{"betaCLI": "true"},
Args: cobra.NoArgs,
Use: "audit-trails",
Short: listAuditTrailsDesc,
Long: listAuditTrailsDesc,
Args: cobra.NoArgs,
Deprecated: "Audit trails are deprecated. Please use Flows and Trail instead.",
PreRunE: func(cmd *cobra.Command, args []string) error {
err := RequireGlobalFlags(global, []string{"Org", "ApiToken"})
if err != nil {
Expand Down
25 changes: 3 additions & 22 deletions cmd/kosli/listAuditTrails_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,42 +32,23 @@ func (suite *ListAuditTrailsCommandTestSuite) SetupTest() {

func (suite *ListAuditTrailsCommandTestSuite) TestListAuditTrailsCmd() {
tests := []cmdTestCase{
// {
// name: "listing audit trails works when there are audit trails",
// cmd: fmt.Sprintf(`list audit-trails %s`, suite.acmeOrgKosliArguments),
// goldenFile: "output/list/list-audit-trails.txt",
// },
{
wantError: true,
name: "listing audit trails works when there are audit trails",
cmd: fmt.Sprintf(`list audit-trails %s`, suite.acmeOrgKosliArguments),
golden: "Error: The audit trail feature is in beta. You can enable the feature by running the following Kosli CLI command (version 2.3.2 or later):\n$ kosli enable beta\nJoin our Slack community for more information: https://www.kosli.com/community/\n",
golden: "Command \"audit-trails\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: You don't have access to the audit trails feature. This feature has been deprecated in favour of Flows and Trails.\n",
},
// {
// name: "listing audit trails works when there are no audit trails",
// cmd: fmt.Sprintf(`list audit-trails %s`, suite.iuOrgKosliArguments),
// golden: "No audit trails were found.\n",
// },
{
wantError: true,
name: "listing audit trails works when there are no audit trails",
cmd: fmt.Sprintf(`list audit-trails %s`, suite.iuOrgKosliArguments),
golden: "Error: The audit trail feature is in beta. You can enable the feature by running the following Kosli CLI command (version 2.3.2 or later):\n$ kosli enable beta\nJoin our Slack community for more information: https://www.kosli.com/community/\n",
golden: "Command \"audit-trails\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: You don't have access to the audit trails feature. This feature has been deprecated in favour of Flows and Trails.\n",
},
// {
// name: "listing audit trails with --output json works when there are audit trails",
// cmd: fmt.Sprintf(`list audit-trails --output json %s`, suite.acmeOrgKosliArguments),
// },
// {
// name: "listing audit trails with --output json works when there are no audit trails",
// cmd: fmt.Sprintf(`list audit-trails --output json %s`, suite.iuOrgKosliArguments),
// golden: "[]\n",
// },
{
wantError: true,
name: "providing an argument causes an error",
cmd: fmt.Sprintf(`list audit-trails xxx %s`, suite.acmeOrgKosliArguments),
golden: "Error: unknown command \"xxx\" for \"kosli list audit-trails\"\n",
golden: "Command \"audit-trails\" is deprecated, Audit trails are deprecated. Please use Flows and Trail instead.\nError: unknown command \"xxx\" for \"kosli list audit-trails\"\n",
},
}

Expand Down
Loading

0 comments on commit d5fbc95

Please sign in to comment.