From 3a4d4b2de7fc0236c27f4a06bbc5d69caad34db7 Mon Sep 17 00:00:00 2001
From: Christopher Fenner <26137398+CCFenner@users.noreply.github.com>
Date: Wed, 29 Apr 2020 14:40:11 +0200
Subject: [PATCH] docs: add general config parameters to GO docs (#1471)

* extract StepConfiguration generation to separate file

* add general options to parameter and config table

* fix test case

* remove telemetry flag from docs

* Revert "extract StepConfiguration generation to separate file"

This reverts commit df80dab8cdc3f9042ac35e84a61d03cbb1023f74.
---
 pkg/generator/helper/docuHelper.go      | 15 ++++++++++++++
 pkg/generator/helper/docuHelper_test.go | 26 ++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/pkg/generator/helper/docuHelper.go b/pkg/generator/helper/docuHelper.go
index 094659599..29a0b138c 100644
--- a/pkg/generator/helper/docuHelper.go
+++ b/pkg/generator/helper/docuHelper.go
@@ -42,6 +42,9 @@ func generateStepDocumentation(stepData config.StepData, docuHelperData DocuHelp
 	tmpl, err := template.New("doc").Funcs(funcMap).Parse(content)
 	checkError(err)
 
+	//add general options like script, verbose, etc.
+	appendGeneralOptionsToParameters(&stepData)
+
 	setDefaultStepParameters(&stepData)
 	// add secrets, context defaults to the step parameters
 	handleStepParameters(&stepData)
@@ -242,6 +245,18 @@ func handleStepParameters(stepData *config.StepData) {
 	sortStepParameters(stepData)
 }
 
+func appendGeneralOptionsToParameters(stepData *config.StepData) {
+	script := config.StepParameters{
+		Name: "script", Type: "Jenkins Script", Mandatory: true,
+		Description: "The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the `commonPipelineEnvironment` for retrieving, e.g. configuration parameters.",
+	}
+	verbose := config.StepParameters{
+		Name: "verbose", Type: "bool", Mandatory: false, Default: false, Scope: []string{"GENERAL"},
+		Description: "verbose output",
+	}
+	stepData.Spec.Inputs.Parameters = append(stepData.Spec.Inputs.Parameters, script, verbose)
+}
+
 func appendSecretsToParameters(stepData *config.StepData) {
 	secrets := stepData.Spec.Inputs.Secrets
 	if secrets != nil {
diff --git a/pkg/generator/helper/docuHelper_test.go b/pkg/generator/helper/docuHelper_test.go
index 91b6da31e..767f687ff 100644
--- a/pkg/generator/helper/docuHelper_test.go
+++ b/pkg/generator/helper/docuHelper_test.go
@@ -12,7 +12,31 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-var expectedResultDocument string = "# testStep\n\n\t## Description\n\nLong Test description\n\n\t\n\t## Prerequisites\n\t\n\tnone\n\n\t\n\t\n\t## Parameters\n\n| name | mandatory | default | possible values |\n| ---- | --------- | ------- | --------------- |\n| `param0` | No | `val0` |  |\n| `param1` | No |  |  |\n| `param2` | Yes |  |  |\n\n * `param0`: param0 description\n * `param1`: param1 description\n * `param2`: param1 description\n\n\t\n\t## Step Configuration\n\nWe recommend to define values of step parameters via [config.yml file](../configuration.md).\n\nIn following sections of the config.yml the configuration is possible:\n\n| parameter | general | step/stage |\n| --------- | ------- | ---------- |\n| `param0` | X |  |\n| `param1` |  |  |\n| `param2` |  |  |\n\n\t\n\t## Side effects\n\t\n\tnone\n\t\n\t## Exceptions\n\t\n\tnone\n\t\n\t## Example\n\n\tnone\n"
+var expectedResultDocument string = "# testStep\n\n\t## Description\n\nLong Test description\n\n\t\n\t" +
+	"## Prerequisites\n\t\n\tnone\n\n\t\n\t\n\t" +
+	"## Parameters\n\n| name | mandatory | default | possible values |\n" +
+	"| ---- | --------- | ------- | --------------- |\n" +
+	"| `param0` | No | `val0` |  |\n" +
+	"| `param1` | No |  |  |\n" +
+	"| `param2` | Yes |  |  |\n" +
+	"| `script` | Yes |  |  |\n" +
+	"| `verbose` | No | `false` |  |\n\n" +
+	" * `param0`: param0 description\n" +
+	" * `param1`: param1 description\n" +
+	" * `param2`: param1 description\n" +
+	" * `script`: The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the `commonPipelineEnvironment` for retrieving, e.g. configuration parameters.\n" +
+	" * `verbose`: verbose output\n\n\t\n\t" +
+	"## Step Configuration\n\nWe recommend to define values of step parameters via [config.yml file](../configuration.md).\n\n" +
+	"In following sections of the config.yml the configuration is possible:\n\n" +
+	"| parameter | general | step/stage |\n" +
+	"| --------- | ------- | ---------- |\n" +
+	"| `param0` | X |  |\n" +
+	"| `param1` |  |  |\n" +
+	"| `param2` |  |  |\n" +
+	"| `verbose` | X |  |\n\n\t\n\t" +
+	"## Side effects\n\t\n\tnone\n\t\n\t" +
+	"## Exceptions\n\t\n\tnone\n\t\n\t" +
+	"## Example\n\n\tnone\n"
 
 func configMetaDataMock(name string) (io.ReadCloser, error) {
 	meta1 := `metadata: