doc: improve stage documentation (#3343)

* remove unnecessary sections in case stage does not contain steps (e.g. confirm stage)
* improve readibiliy of condition section
* fix naming

pkg/documentation/generator/main.go

@@ -294,7 +294,7 @@ func createPipelineOverviewDocumentation(stageRunConfig *config.RunConfigV1, sta
 const stepConditionDetails = `!!! note "Step condition details"
     There are currently several conditions which can be checked.<br />**Important: It will be sufficient that any one condition per step is met.**
 
-    * ` + "`" + `config key` + "`" + `: Checks if a defined configuration parameter is set.
+    * ` + "`" + `config` + "`" + `: Checks if a defined configuration parameter is set.
     * ` + "`" + `config value` + "`" + `: Checks if a configuration parameter has a defined value.
     * ` + "`" + `file pattern` + "`" + `: Checks if files according a defined pattern exist in the project.
 	* ` + "`" + `file pattern from config` + "`" + `: Checks if files according a pattern defined in the custom configuration exist in the project.
@@ -313,47 +313,49 @@ func createPipelineStageDocumentation(stageRunConfig *config.RunConfigV1, stageT
 	for _, stage := range stageRunConfig.PipelineConfig.Spec.Stages {
 		stageDoc := fmt.Sprintf("# %v\n\n", stage.DisplayName)
 		stageDoc += fmt.Sprintf("%v\n\n", stage.Description)
-		stageDoc += "## Stage Content\n\nThis stage comprises following steps which are activated depending on your use-case/configuration:\n\n"
 
-		for i, step := range stage.Steps {
+		if len(stage.Steps) > 0 {
-			if i == 0 {
+			stageDoc += "## Stage Content\n\nThis stage comprises following steps which are activated depending on your use-case/configuration:\n\n"
-				stageDoc += "| step | step description |\n"
+
-				stageDoc += "| ---- | ---------------- |\n"
+			for i, step := range stage.Steps {
+				if i == 0 {
+					stageDoc += "| step | step description |\n"
+					stageDoc += "| ---- | ---------------- |\n"
+				}
+
+				orchestratorBadges := ""
+				for _, orchestrator := range step.Orchestrators {
+					orchestratorBadges += getBadge(orchestrator) + " "
+				}
+
+				stageDoc += fmt.Sprintf("| [%v](%v/%v.md) | %v%v |\n", step.Name, relativeStepsPath, step.Name, orchestratorBadges, step.Description)
 			}
 
-			orchestratorBadges := ""
+			stageDoc += "\n"
-			for _, orchestrator := range step.Orchestrators {
+
-				orchestratorBadges += getBadge(orchestrator) + " "
+			stageDoc += "## Stage & Step Activation\n\nThis stage will be active in case one of following conditions are met:\n\n"
+			stageDoc += "* One of the steps is explicitly activated by using `<stepName>: true` in the stage configuration\n"
+			stageDoc += "* At least one of the step conditions is met and steps are not explicitly deactivated by using `<stepName>: false` in the stage configuration\n\n"
+
+			stageDoc += stepConditionDetails
+			stageDoc += overrulingStepActivation
+
+			stageDoc += "Following conditions apply for activation of steps contained in the stage:\n\n"
+
+			stageDoc += "| step | active if one of following conditions is met |\n"
+			stageDoc += "| ---- | -------------------------------------------- |\n"
+
+			// add step condition details
+			for _, step := range stage.Steps {
+				stageDoc += fmt.Sprintf("| [%v](%v/%v.md) | %v |\n", step.Name, relativeStepsPath, step.Name, getStepConditionDetails(step))
 			}
 
-			stageDoc += fmt.Sprintf("| [%v](%v/%v.md) | %v%v |\n", step.Name, relativeStepsPath, step.Name, orchestratorBadges, step.Description)
+			stageFilePath := filepath.Join(stageTargetPath, fmt.Sprintf("%v.md", stage.Name))
+			fmt.Println("writing file", stageFilePath)
+			if err := utils.FileWrite(stageFilePath, []byte(stageDoc), 0666); err != nil {
+				return fmt.Errorf("failed to write stage file '%v': %w", stageFilePath, err)
+			}
 		}
-
-		stageDoc += "\n"
-
-		stageDoc += "## Stage & Step Activation\n\nThis stage will be active in case one of following conditions are met:\n\n"
-		stageDoc += "* One of the steps is explicitly activated by using `<stepName>: true` in the stage configuration\n"
-		stageDoc += "* At least one of the step conditions is met and steps are not explicitly deactivated by using `<stepName>: false` in the stage configuration\n\n"
-
-		stageDoc += stepConditionDetails
-		stageDoc += overrulingStepActivation
-
-		stageDoc += "Following conditions apply for activation of steps contained in the stage:\n\n"
-
-		stageDoc += "| step | active if one of following conditions is met |\n"
-		stageDoc += "| ---- | -------------------------------------------- |\n"
-
-		// add step condition details
-		for _, step := range stage.Steps {
-			stageDoc += fmt.Sprintf("| [%v](%v/%v.md) | %v |\n", step.Name, relativeStepsPath, step.Name, getStepConditionDetails(step))
-		}
-
-		stageFilePath := filepath.Join(stageTargetPath, fmt.Sprintf("%v.md", stage.Name))
-		fmt.Println("writing file", stageFilePath)
-		if err := utils.FileWrite(stageFilePath, []byte(stageDoc), 0666); err != nil {
-			return fmt.Errorf("failed to write stage file '%v': %w", stageFilePath, err)
-		}
-
 	}
 	return nil
 }
@@ -395,22 +397,22 @@ func getStepConditionDetails(step config.Step) string {
 		}
 
 		if len(condition.ConfigKey) > 0 {
-			stepConditions += fmt.Sprintf("<i>config key:</i><ul><li>`%v`</li></ul>", condition.ConfigKey)
+			stepConditions += fmt.Sprintf("<i>config key:</i>&nbsp;`%v`<br />", condition.ConfigKey)
 			continue
 		}
 
 		if len(condition.FilePattern) > 0 {
-			stepConditions += fmt.Sprintf("<i>file pattern:</i><ul><li>`%v`</li></ul>", condition.FilePattern)
+			stepConditions += fmt.Sprintf("<i>file pattern:</i>&nbsp;`%v`<br />", condition.FilePattern)
 			continue
 		}
 
 		if len(condition.FilePatternFromConfig) > 0 {
-			stepConditions += fmt.Sprintf("<i>file pattern from config:</i><ul><li>`%v`</li></ul>", condition.FilePatternFromConfig)
+			stepConditions += fmt.Sprintf("<i>file pattern from config:</i>&nbsp;`%v`<br />", condition.FilePatternFromConfig)
 			continue
 		}
 
 		if len(condition.NpmScript) > 0 {
-			stepConditions += fmt.Sprintf("<i>npm script:</i><ul><li>`%v`</li></ul>", condition.NpmScript)
+			stepConditions += fmt.Sprintf("<i>npm script:</i>&nbsp;`%v`<br />", condition.NpmScript)
 			continue
 		}
 

pkg/documentation/generator/main_test.go

@@ -115,12 +115,12 @@ func TestGetStepConditionDetails(t *testing.T) {
 	}{
 		{name: "noCondition", step: config.Step{Conditions: []config.StepCondition{}}, expected: "**active** by default - deactivate explicitly"},
 		{name: "config", step: config.Step{Conditions: []config.StepCondition{{Config: map[string][]interface{}{"configKey1": {"keyVal1", "keyVal2"}}}}}, expected: "<i>config:</i><ul><li>`configKey1`: `keyVal1`</li><li>`configKey1`: `keyVal2`</li></ul>"},
-		{name: "configKey", step: config.Step{Conditions: []config.StepCondition{{ConfigKey: "configKey"}}}, expected: "<i>config key:</i><ul><li>`configKey`</li></ul>"},
+		{name: "configKey", step: config.Step{Conditions: []config.StepCondition{{ConfigKey: "configKey"}}}, expected: "<i>config key:</i>&nbsp;`configKey`<br />"},
-		{name: "filePattern", step: config.Step{Conditions: []config.StepCondition{{FilePattern: "testPattern"}}}, expected: "<i>file pattern:</i><ul><li>`testPattern`</li></ul>"},
+		{name: "filePattern", step: config.Step{Conditions: []config.StepCondition{{FilePattern: "testPattern"}}}, expected: "<i>file pattern:</i>&nbsp;`testPattern`<br />"},
-		{name: "filePatternFromConfig", step: config.Step{Conditions: []config.StepCondition{{FilePatternFromConfig: "patternConfigKey"}}}, expected: "<i>file pattern from config:</i><ul><li>`patternConfigKey`</li></ul>"},
+		{name: "filePatternFromConfig", step: config.Step{Conditions: []config.StepCondition{{FilePatternFromConfig: "patternConfigKey"}}}, expected: "<i>file pattern from config:</i>&nbsp;`patternConfigKey`<br />"},
 		{name: "inactive", step: config.Step{Conditions: []config.StepCondition{{Inactive: true}}}, expected: "**inactive** by default - activate explicitly"},
-		{name: "npmScript", step: config.Step{Conditions: []config.StepCondition{{NpmScript: "testScript"}}}, expected: "<i>npm script:</i><ul><li>`testScript`</li></ul>"},
+		{name: "npmScript", step: config.Step{Conditions: []config.StepCondition{{NpmScript: "testScript"}}}, expected: "<i>npm script:</i>&nbsp;`testScript`<br />"},
-		{name: "multiple conditions", step: config.Step{Conditions: []config.StepCondition{{ConfigKey: "configKey"}, {FilePattern: "testPattern"}}}, expected: "<i>config key:</i><ul><li>`configKey`</li></ul><i>file pattern:</i><ul><li>`testPattern`</li></ul>"},
+		{name: "multiple conditions", step: config.Step{Conditions: []config.StepCondition{{ConfigKey: "configKey"}, {FilePattern: "testPattern"}}}, expected: "<i>config key:</i>&nbsp;`configKey`<br /><i>file pattern:</i>&nbsp;`testPattern`<br />"},
 	}
 
 	for _, test := range tt {