Tweak client ref doc page (#555)

* Show a commands shell-synopsis directly below the synopsis title

* Add link in commands Examples text on how to set flags via env-var or config file

* Update golden snyk.md used in docs page test

* Update dev-guide.md with instructions on how to run tests

Author: JonJagger

cmd/kosli/docs.go

@@ -131,13 +131,12 @@ func KosliGenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(st
 
 	if len(cmd.Long) > 0 {
 		buf.WriteString("## Synopsis\n\n")
+		if cmd.Runnable() {
+			buf.WriteString(fmt.Sprintf("```shell\n%s\n```\n\n", cmd.UseLine()))
+		}
 		buf.WriteString(strings.Replace(cmd.Long, "^", "`", -1) + "\n\n")
 	}
 
-	if cmd.Runnable() {
-		buf.WriteString(fmt.Sprintf("```shell\n%s\n```\n\n", cmd.UseLine()))
-	}
-
 	if err := printOptions(buf, cmd, name); err != nil {
 		return err
 	}
@@ -181,7 +180,9 @@ 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")
+		url := "https://docs.kosli.com/getting_started/install/#assigning-flags-via-environment-variables"
+		message := fmt.Sprintf("These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](%v). \n\n", url)
+		buf.WriteString(message)
 
 		// 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

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

@@ -9,6 +9,10 @@ summary: "Report a snyk attestation to an artifact or a trail in a Kosli flow.
 
 ## Synopsis
 
+```shell
+snyk [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]
+```
+
 Report a snyk attestation to an artifact or a trail in a Kosli flow.  
 Only SARIF snyk output is accepted. 
 Snyk output can be for "snyk code test", "snyk container test", or "snyk iac test".
@@ -29,10 +33,6 @@ You can optionally redact some of the git commit data sent to Kosli using `--red
 Note that when the attestation is reported for an artifact that does not yet exist in Kosli, `--commit` is required to facilitate
 binding the attestation to the right artifact.
 
-```shell
-snyk [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]
-```
-
 ## Flags
 | Flag | Description |
 | :--- | :--- |
@@ -62,7 +62,7 @@ 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. 
+These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](https://docs.kosli.com/getting_started/install/#assigning-flags-via-environment-variables). 
 
 **report a snyk attestation about a pre-built docker artifact (kosli calculates the fingerprint)**
 

dev-guide.md

@@ -39,5 +39,14 @@ Then to run Kosli commands:
 
 ## Running the tests
 
+To run the tests you need to set the env-var `KOSLI_API_TOKEN_PROD`
+to an api-token (with reader rights), for the `kosli` Org on https://app.kosli.com
+
+To run all tests except the too slow ones:
+`make test_integration` 
+
+To run all the tests"
+`make test_integration_full`
+
 To run only the tests in a single test suite, eg TestAttestJunitCommandTestSuite
 `make test_integration_single TARGET=TestAttestJunitCommandTestSuite`