jenkins/sap-jenkins-library
1
0
Fork 0
mirror of https://github.com/SAP/jenkins-library.git synced 2025-09-16 09:26:22 +02:00
Code Issues Releases Activity

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

Browse Source 
enhance documentation generation to properly reflect
parameters which are conditionally mandatory.
This commit is contained in:
Oliver Nocon
2021-10-12 12:49:38 +02:00
committed by GitHub
parent ba694b6737
commit db6b465ff1
2 changed files with 99 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
pkg/documentation/generator/parameters.go
View File

@@ -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

38
pkg/documentation/generator/parameters_test.go
View File

@@ -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,6 +150,7 @@ func TestCheckParameterInfo(t *testing.T) {
}
func TestCreateParameterDetails(t *testing.T) {
t.Run("default", func(t *testing.T) {
stepData := config.StepData{
Spec: config.StepSpec{
Inputs: config.StepInputs{
@@ -179,6 +184,28 @@ func TestCreateParameterDetails(t *testing.T) {
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`")
})
}
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)
})
}