Merge branch 'master' into pr/seeAnnotationInDocu

documentation/docs/steps/dockerExecute.md

@@ -2,47 +2,11 @@
 
 ## Description
 
-Executes a closure inside a docker container with the specified docker image.
-The workspace is mounted into the docker image.
-Proxy environment variables defined on the Jenkins machine are also available in the Docker container.
+Content here is generated from corresponnding step, see `vars`.
 
 ## Parameters
-| parameter | mandatory | default | possible values |
-| ----------|-----------|---------|-----------------|
-|script|yes|||
-|containerCommand|no|||
-|containerPortMappings|no|||
-|containerShell|no|||
-|dockerEnvVars|no|`[:]`||
-|dockerImage|no|`''`||
-|dockerName|no|||
-|dockerOptions|no|`''`||
-|dockerVolumeBind|no|`[:]`||
-|dockerWorkspace|no|||
-|jenkinsKubernetes|no|`[jnlpAgent:s4sdk/jenkins-agent-k8s:latest]`||
-|sidecarEnvVars|no|||
-|sidecarImage|no|||
-|sidecarName|no|||
-|sidecarOptions|no|||
-|sidecarVolumeBind|no|||
-|sidecarWorkspace|no|||
 
-* `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration.
-* `containerCommand`: only used in case exeuction environment is Kubernetes, allows to specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
-* `containerPortMappings`: Map which defines per docker image the port mappings, like `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`
-* `containerShell`: only used in case exeuction environment is Kubernetes, allows to specify the shell to be used for execution of commands
-* `dockerEnvVars`: Environment variables to set in the container, e.g. [http_proxy:'proxy:8080']
-* `dockerImage`: Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.
-* `dockerName`: Kubernetes case: Name of the container launching `dockerImage`, SideCar: Name of the container in local network
-* `dockerOptions` Docker options to be set when starting the container. It can be a list or a string.
-* `dockerVolumeBind` Volumes that should be mounted into the container.
-* `dockerWorkspace`: only relevant for Kubernetes case: specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`
-* `sidecarEnvVars` defines environment variables for the sidecar container, similar to `dockerEnvVars`
-* `sidecarImage`: Name of the docker image of the sidecar container. Do not provide this value if no sidecar container is required.
-* `sidecarName`: as `dockerName` for the sidecar container
-* `sidecarOptions`: as `dockerOptions` for the sidecar container
-* `sidecarVolumeBind`: as `dockerVolumeBind` for the sidecar container
-* `sidecarWorkspace`: as `dockerWorkspace` for the sidecar container
+Content here is generated from corresponnding step, see `vars`.
 
 ## Kubernetes support
 
@@ -50,27 +14,7 @@ If the Jenkins is setup on a Kubernetes cluster, then you can execute the closur
 
 ## Step configuration
 
-We recommend to define values of step parameters via [config.yml file](../configuration.md).
-
-In following sections the configuration is possible:
-
-| parameter | general | step | stage |
-| ----------|-----------|---------|-----------------|
-|script||||
-|containerPortMappings||X|X|
-|dockerEnvVars||X|X|
-|dockerImage||X|X|
-|dockerName||X|X|
-|dockerOptions||X|X|
-|dockerVolumeBind||X|X|
-|dockerWorkspace||X|X|
-|jenkinsKubernetes|X|||
-|sidecarEnvVars||X|X|
-|sidecarImage||X|X|
-|sidecarName||X|X|
-|sidecarOptions||X|X|
-|sidecarVolumeBind||X|X|
-|sidecarWorkspace||X|X|
+Content here is generated from corresponnding step, see `vars`.
 
 ## Side effects
 

vars/dockerExecute.groovy

@@ -3,6 +3,7 @@ import static com.sap.piper.Prerequisites.checkScript
 import com.cloudbees.groovy.cps.NonCPS
 
 import com.sap.piper.ConfigurationHelper
+import com.sap.piper.GenerateDocumentation
 import com.sap.piper.JenkinsUtils
 import com.sap.piper.Utils
 import com.sap.piper.k8s.ContainerMap
@@ -13,28 +14,91 @@ import groovy.transform.Field
 @Field def PLUGIN_ID_DOCKER_WORKFLOW = 'docker-workflow'
 
 @Field Set GENERAL_CONFIG_KEYS = [
+    /**
+     *
+     */
     'jenkinsKubernetes'
 ]
 @Field Set STEP_CONFIG_KEYS = GENERAL_CONFIG_KEYS.plus([
-    'containerPortMappings',
+    /**
+     * Kubernetes only:
+     * Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
+     */
     'containerCommand',
+    /**
+     * Map which defines per docker image the port mappings, e.g. `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`.
+     */
+    'containerPortMappings',
+    /**
+     * Kubernetes only:
+     * Allows to specify the shell to be used for execution of commands.
+     */
     'containerShell',
+    /**
+     * Environment variables to set in the container, e.g. [http_proxy: 'proxy:8080'].
+     */
     'dockerEnvVars',
+    /**
+     * Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.
+     */
     'dockerImage',
+    /**
+     * Kubernetes only:
+     * Name of the container launching `dockerImage`.
+     * SideCar only:
+     * Name of the container in local network.
+     */
     'dockerName',
+    /**
+     * Docker options to be set when starting the container (List or String).
+     */
     'dockerOptions',
-    'dockerWorkspace',
+    /**
+     * Volumes that should be mounted into the container.
+     */
     'dockerVolumeBind',
+    /**
+     * Kubernetes only:
+     * Specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`.
+     */
+    'dockerWorkspace',
+    /**
+     * as `dockerEnvVars` for the sidecar container
+     */
     'sidecarEnvVars',
+    /**
+     * as `dockerImage` for the sidecar container
+     */
     'sidecarImage',
+    /**
+     * as `dockerName` for the sidecar container
+     */
     'sidecarName',
+    /**
+     * as `dockerOptions` for the sidecar container
+     */
     'sidecarOptions',
-    'sidecarWorkspace',
+    /**
+     * as `dockerVolumeBind` for the sidecar container
+     */
     'sidecarVolumeBind',
+    /**
+     * as `dockerWorkspace` for the sidecar container
+     */
+    'sidecarWorkspace',
+    /**
+     * Specific stashes that should be considered for the step execution.
+     */
     'stashContent'
 ])
 @Field Set PARAMETER_KEYS = STEP_CONFIG_KEYS
 
+/**
+ * Executes a closure inside a docker container with the specified docker image.
+ * The workspace is mounted into the docker image.
+ * Proxy environment variables defined on the Jenkins machine are also available in the Docker container.
+ */
+@GenerateDocumentation
 void call(Map parameters = [:], body) {
     handlePipelineStepErrors(stepName: STEP_NAME, stepParameters: parameters) {
 
@@ -154,7 +218,7 @@ void call(Map parameters = [:], body) {
 
 
 
-/**
+/*
  * Returns a string with docker options containing
  * environment variables (if set).
  * Possible to extend with further options.
@@ -225,7 +289,7 @@ boolean isKubernetes() {
     return Boolean.valueOf(env.ON_K8S)
 }
 
-/**
+/*
  * Escapes blanks for values in key/value pairs
  * E.g. <code>description=Lorem ipsum</code> is
  * changed to <code>description=Lorem\ ipsum</code>.