Don't show api-token,host,org,flow,trail in example use cases

cmd/kosli/docs.go

@@ -11,6 +11,7 @@ import (
 	"path"
 	"path/filepath"
 	"strings"
+	"unicode"
 
 	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
@@ -180,6 +181,7 @@ func KosliGenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(st
 		// Note: The contents of the title lines could also contain < and > characters which will
 		// be lost if simply embedded in a md ## section.
 		buf.WriteString("## Examples Use Cases\n\n")
+		buf.WriteString("These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are set/provided. \n\n")
 
 		// Some non-title lines contain a # character, (eg in a snappish) so we have to
 		// split on newlines first and then only split on # in the first position
@@ -226,12 +228,36 @@ func hashTitledExamples(lines []string) [][]string {
 			result = append(result, example) // See result[1:] at end
 			example = make([]string, 0)
 		}
-		example = append(example, line)
+		if !isSetWithEnvVar(line) {
+			example = append(example, choppedLineContinuation(line))
+		}
 	}
 	result = append(result, example)
 	return result[1:]
 }
 
+func isSetWithEnvVar(line string) bool {
+	trimmed_line := strings.TrimSpace(line)
+	if strings.HasPrefix(trimmed_line, "--api-token ") {
+		return true
+	} else if strings.HasPrefix(trimmed_line, "--host ") {
+		return true
+	} else if strings.HasPrefix(trimmed_line, "--org ") {
+		return true
+	} else if strings.HasPrefix(trimmed_line, "--flow ") {
+		return true
+	} else if strings.HasPrefix(trimmed_line, "--trail ") {
+		return true
+	} else {
+		return false
+	}
+}
+
+func choppedLineContinuation(line string) string {
+	trimmed_line := strings.TrimRightFunc(line, unicode.IsSpace)
+	return strings.TrimSuffix(trimmed_line, "\\")
+}
+
 func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
 	flags := cmd.NonInheritedFlags()
 	flags.SetOutput(buf)

cmd/kosli/docs_test.go

@@ -17,8 +17,18 @@ type DocsCommandTestSuite struct {
 }
 
 func (suite *DocsCommandTestSuite) TestDocsCmd() {
+	// If this test fails, a simple way to retrieve a new generated master is to:
+	// - add an import for fmt
+	// - uncomment the fmt.Printf() call below
+	// - comment out the line defer os.RemoveAll(tempDirName)
+	// Then:
+	// - make test_integration_single TARGET=TestDocsCommandTestSuite
+	// will tell you where the new snyk.md master file lives.
+	// Then copy it to ./cmd/kosli/testdata/output/docs/
+	// and undo the changes above.
 	global = &GlobalOpts{}
 	tempDirName, err := os.MkdirTemp("", "generatedDocs")
+	//fmt.Printf("tempDirName :%s:\n\n\n\n\n", tempDirName)
 	require.NoError(suite.Suite.T(), err)
 	defer os.RemoveAll(tempDirName)
 

cmd/kosli/testdata/output/docs/snyk.md

@@ -62,85 +62,63 @@ snyk [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]
 
 ## Examples Use Cases
 
+These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are set/provided. 
+
 **report a snyk attestation about a pre-built docker artifact (kosli calculates the fingerprint)**
 
 ```shell
-kosli attest snyk yourDockerImageName \
-	--artifact-type docker \
-	--name yourAttestationName \
-	--flow yourFlowName \
-	--trail yourTrailName \
-	--scan-results yourSnykSARIFScanResults \
-	--api-token yourAPIToken \
-	--org yourOrgName
+kosli attest snyk yourDockerImageName 
+	--artifact-type docker 
+	--name yourAttestationName 
+	--scan-results yourSnykSARIFScanResults 
 
 ```
 
 **report a snyk attestation about a pre-built docker artifact (you provide the fingerprint)**
 
 ```shell
-kosli attest snyk \
-	--fingerprint yourDockerImageFingerprint \
-	--name yourAttestationName \
-	--flow yourFlowName \
-	--trail yourTrailName \
-	--scan-results yourSnykSARIFScanResults \
-	--api-token yourAPIToken \
-	--org yourOrgName
+kosli attest snyk 
+	--fingerprint yourDockerImageFingerprint 
+	--name yourAttestationName 
+	--scan-results yourSnykSARIFScanResults 
 
 ```
 
 **report a snyk attestation about a trail**
 
 ```shell
-kosli attest snyk \
-	--name yourAttestationName \
-	--flow yourFlowName \
-	--trail yourTrailName \
-	--scan-results yourSnykSARIFScanResults \
-	--api-token yourAPIToken \
-	--org yourOrgName
+kosli attest snyk 
+	--name yourAttestationName 
+	--scan-results yourSnykSARIFScanResults 
 
 ```
 
 **report a snyk attestation about an artifact which has not been reported yet in a trail**
 
 ```shell
-kosli attest snyk \
-	--name yourTemplateArtifactName.yourAttestationName \
-	--flow yourFlowName \
-	--trail yourTrailName \
-	--commit yourArtifactGitCommit \
-	--scan-results yourSnykSARIFScanResults \
-	--api-token yourAPIToken \
-	--org yourOrgName
+kosli attest snyk 
+	--name yourTemplateArtifactName.yourAttestationName 
+	--commit yourArtifactGitCommit 
+	--scan-results yourSnykSARIFScanResults 
 
 ```
 
 **report a snyk attestation about a trail with an attachment**
 
 ```shell
-kosli attest snyk \
-	--name yourAttestationName \
-	--flow yourFlowName \
-	--trail yourTrailName \
-	--scan-results yourSnykSARIFScanResults \
-	--attachments yourEvidencePathName \
-	--api-token yourAPIToken \
-	--org yourOrgName
+kosli attest snyk 
+	--name yourAttestationName 
+	--scan-results yourSnykSARIFScanResults 
+	--attachments yourEvidencePathName 
 
 ```
 
 **report a snyk attestation about a trail without uploading the snyk results file**
 
 ```shell
-kosli attest snyk \
-	--name yourAttestationName \
-	--flow yourFlowName \
-	--trail yourTrailName \
-	--scan-results yourSnykSARIFScanResults \
-	--upload-results=false \
-	--api-token yourAPIToken \
-	--org yourOrgName
+kosli attest snyk 
+	--name yourAttestationName 
+	--scan-results yourSnykSARIFScanResults 
+	--upload-results=false 
 ```