chore(doc): conditionally mandatory parameters (#3172)

enhance documentation generation to properly reflect parameters which are conditionally mandatory.
2025-09-16 09:26:22 +02:00 · 2021-10-12 12:49:38 +02:00
parent ba694b6737
commit db6b465ff1
2 changed files with 99 additions and 36 deletions
--- a/pkg/documentation/generator/parameters.go
+++ b/pkg/documentation/generator/parameters.go
@@ -31,6 +31,31 @@ func createParametersSection(stepData *config.StepData) string {
 	return parameters
 }

+func parameterMandatoryInformation(param config.StepParameters, furtherInfo string) (mandatory bool, mandatoryString string, mandatoryInfo string) {
+	mandatory = param.Mandatory
+	mandatoryInfo = furtherInfo
+
+	mandatoryIf := param.MandatoryIf
+	if len(mandatoryIf) > 0 {
+		mandatory = true
+		if len(mandatoryInfo) > 0 {
+			mandatoryInfo += "<br />"
+		}
+		furtherInfoConditions := []string{"mandatory in case of:"}
+		for _, mandatoryCondition := range mandatoryIf {
+			furtherInfoConditions = append(furtherInfoConditions, fmt.Sprintf("- [`%v`](#%v)=`%v`", mandatoryCondition.Name, strings.ToLower(mandatoryCondition.Name), mandatoryCondition.Value))
+		}
+
+		mandatoryInfo += strings.Join(furtherInfoConditions, "<br />")
+	}
+
+	mandatoryString = "**yes**"
+	if len(mandatoryInfo) > 0 {
+		mandatoryString = "**(yes)**"
+	}
+	return
+}
+
 func createParameterOverview(stepData *config.StepData, executionEnvironment bool) string {
 	var table = "| Name | Mandatory | Additional information |\n"
 	table += "| ---- | --------- | ---------------------- |\n"
@@ -38,7 +63,11 @@ func createParameterOverview(stepData *config.StepData, executionEnvironment boo
 	for _, param := range stepData.Spec.Inputs.Parameters {
 		furtherInfo, err := parameterFurtherInfo(param.Name, stepData, executionEnvironment)
 		if err == nil {
-			table += fmt.Sprintf("| [%v](#%v) | %v | %v |\n", param.Name, strings.ToLower(param.Name), ifThenElse(param.Mandatory, "**yes**", "no"), furtherInfo)
+
+			var mandatory bool
+			var mandatoryString string
+			mandatory, mandatoryString, furtherInfo = parameterMandatoryInformation(param, furtherInfo)
+			table += fmt.Sprintf("| [%v](#%v) | %v | %v |\n", param.Name, strings.ToLower(param.Name), ifThenElse(mandatory, mandatoryString, "no"), furtherInfo)
 		}
 	}

@@ -132,7 +161,11 @@ func createParameterDetails(stepData *config.StepData) string {

 		details += fmt.Sprintf("| Aliases | %v |\n", aliasList(param.Aliases))
 		details += fmt.Sprintf("| Type | `%v` |\n", param.Type)
-		details += fmt.Sprintf("| Mandatory | %v |\n", ifThenElse(param.Mandatory, "**yes**", "no"))
+		mandatory, mandatoryString, furtherInfo := parameterMandatoryInformation(param, "")
+		if mandatory && len(furtherInfo) > 0 {
+			mandatoryString = furtherInfo
+		}
+		details += fmt.Sprintf("| Mandatory | %v |\n", ifThenElse(mandatory, mandatoryString, "no"))
 		details += fmt.Sprintf("| Default | %v |\n", formatDefault(param, stepParameterNames))
 		if param.PossibleValues != nil {
 			details += fmt.Sprintf("| Possible values | %v |\n", possibleValueList(param.PossibleValues))
@@ -308,9 +341,9 @@ func sortStepParameters(stepData *config.StepData, considerMandatory bool) {

 		if considerMandatory {
 			sort.SliceStable(parameters[:], func(i, j int) bool {
-				if parameters[i].Mandatory == parameters[j].Mandatory {
+				if (parameters[i].Mandatory || len(parameters[i].MandatoryIf) > 0) == (parameters[j].Mandatory || len(parameters[j].MandatoryIf) > 0) {
 					return strings.Compare(parameters[i].Name, parameters[j].Name) < 0
-				} else if parameters[i].Mandatory {
+				} else if parameters[i].Mandatory || len(parameters[i].MandatoryIf) > 0 {
 					return true
 				}
 				return false
--- a/pkg/documentation/generator/parameters_test.go
+++ b/pkg/documentation/generator/parameters_test.go
@@ -18,19 +18,23 @@ func TestCreateParameterOverview(t *testing.T) {
 				},
 				Parameters: []config.StepParameters{
 					{Name: "param1"},
+					{Name: "param2", Mandatory: true},
+					{Name: "param3", MandatoryIf: []config.ParameterDependence{{Name: "param1", Value: "param3Necessary"}}},
 					{Name: "dockerImage", Default: "testImage"},
 					{Name: "stashContent", Default: "testStash"},
 				},
 			},
 		},
 	}
-	stepParameterNames = []string{"param1"}
+	stepParameterNames = []string{"param1", "param2", "param3"}

 	t.Run("Test Step Section", func(t *testing.T) {

 		expected := `| Name | Mandatory | Additional information |
 | ---- | --------- | ---------------------- |
 | [param1](#param1) | no |  |
+| [param2](#param2) | **yes** |  |
+| [param3](#param3) | **(yes)** | mandatory in case of:<br />- ` + "[`param1`](#param1)=`param3Necessary`" + ` |

 `

@@ -146,39 +150,62 @@ func TestCheckParameterInfo(t *testing.T) {
 }

 func TestCreateParameterDetails(t *testing.T) {
-	stepData := config.StepData{
-		Spec: config.StepSpec{
-			Inputs: config.StepInputs{
-				Parameters: []config.StepParameters{
-					{
-						Name:            "param1",
-						Aliases:         []config.Alias{{Name: "param1Alias"}, {Name: "paramAliasDeprecated", Deprecated: true}},
-						Mandatory:       true,
-						Default:         "param1Default",
-						LongDescription: "long description",
-						PossibleValues:  []interface{}{"val1", "val2"},
-						Scope:           []string{"STEPS"},
-						Secret:          true,
-						Type:            "string",
+	t.Run("default", func(t *testing.T) {
+		stepData := config.StepData{
+			Spec: config.StepSpec{
+				Inputs: config.StepInputs{
+					Parameters: []config.StepParameters{
+						{
+							Name:            "param1",
+							Aliases:         []config.Alias{{Name: "param1Alias"}, {Name: "paramAliasDeprecated", Deprecated: true}},
+							Mandatory:       true,
+							Default:         "param1Default",
+							LongDescription: "long description",
+							PossibleValues:  []interface{}{"val1", "val2"},
+							Scope:           []string{"STEPS"},
+							Secret:          true,
+							Type:            "string",
+						},
 					},
 				},
 			},
-		},
-	}
+		}

-	res := createParameterDetails(&stepData)
+		res := createParameterDetails(&stepData)
+
+		assert.Contains(t, res, "#### param1")
+		assert.Contains(t, res, "long description")
+		assert.Contains(t, res, "`param1Alias`")
+		assert.Contains(t, res, "`paramAliasDeprecated` (**deprecated**)")
+		assert.Contains(t, res, "string")
+		assert.Contains(t, res, "param1Default")
+		assert.Contains(t, res, "val1")
+		assert.Contains(t, res, "val2")
+		assert.Contains(t, res, "no")
+		assert.Contains(t, res, "**yes**")
+		assert.Contains(t, res, "steps")
+	})
+
+	t.Run("conditional mandatory parameters", func(t *testing.T) {
+		stepData := config.StepData{
+			Spec: config.StepSpec{
+				Inputs: config.StepInputs{
+					Parameters: []config.StepParameters{
+						{
+							Name:        "param2",
+							MandatoryIf: []config.ParameterDependence{{Name: "param1", Value: "param1Val"}},
+							Type:        "string",
+						},
+					},
+				},
+			},
+		}
+
+		res := createParameterDetails(&stepData)
+
+		assert.Contains(t, res, "mandatory in case of:<br />- [`param1`](#param1)=`param1Val`")
+	})

-	assert.Contains(t, res, "#### param1")
-	assert.Contains(t, res, "long description")
-	assert.Contains(t, res, "`param1Alias`")
-	assert.Contains(t, res, "`paramAliasDeprecated` (**deprecated**)")
-	assert.Contains(t, res, "string")
-	assert.Contains(t, res, "param1Default")
-	assert.Contains(t, res, "val1")
-	assert.Contains(t, res, "val2")
-	assert.Contains(t, res, "no")
-	assert.Contains(t, res, "**yes**")
-	assert.Contains(t, res, "steps")
 }

 func TestFormatDefault(t *testing.T) {
@@ -339,6 +366,7 @@ func TestSortStepParameters(t *testing.T) {
 					{Name: "ab6", Mandatory: true},
 					{Name: "ab4", Mandatory: false},
 					{Name: "ab2", Mandatory: true},
+					{Name: "ab7", MandatoryIf: []config.ParameterDependence{{Name: "ab1", Value: "ab1Val1"}}},
 				},
 			},
 		},
@@ -353,6 +381,7 @@ func TestSortStepParameters(t *testing.T) {
 		assert.Equal(t, "ab4", stepData.Spec.Inputs.Parameters[3].Name)
 		assert.Equal(t, "ab5", stepData.Spec.Inputs.Parameters[4].Name)
 		assert.Equal(t, "ab6", stepData.Spec.Inputs.Parameters[5].Name)
+		assert.Equal(t, "ab7", stepData.Spec.Inputs.Parameters[6].Name)
 	})

 	t.Run("consider mandatory", func(t *testing.T) {
@@ -361,8 +390,9 @@ func TestSortStepParameters(t *testing.T) {
 		assert.Equal(t, "ab2", stepData.Spec.Inputs.Parameters[0].Name)
 		assert.Equal(t, "ab3", stepData.Spec.Inputs.Parameters[1].Name)
 		assert.Equal(t, "ab6", stepData.Spec.Inputs.Parameters[2].Name)
-		assert.Equal(t, "ab1", stepData.Spec.Inputs.Parameters[3].Name)
-		assert.Equal(t, "ab4", stepData.Spec.Inputs.Parameters[4].Name)
-		assert.Equal(t, "ab5", stepData.Spec.Inputs.Parameters[5].Name)
+		assert.Equal(t, "ab7", stepData.Spec.Inputs.Parameters[3].Name)
+		assert.Equal(t, "ab1", stepData.Spec.Inputs.Parameters[4].Name)
+		assert.Equal(t, "ab4", stepData.Spec.Inputs.Parameters[5].Name)
+		assert.Equal(t, "ab5", stepData.Spec.Inputs.Parameters[6].Name)
 	})
 }