docs: make used library and binary name in samples exchangeable for custom steps (#2092)

* add code block type

* add parameters to hand in library and binary name

* use library and binary name parameters

* add test cases

* use yaml file to distintuish custom from regular steps

* add test case

pkg/documentation/generator.go

@@ -9,19 +9,32 @@ import (
 
 	generator "github.com/SAP/jenkins-library/pkg/documentation/generator"
 	"github.com/SAP/jenkins-library/pkg/generator/helper"
+	"github.com/ghodss/yaml"
 )
 
 func main() {
 	var metadataPath string
 	var docTemplatePath string
+	var customLibraryStepFile string
 
 	flag.StringVar(&metadataPath, "metadataDir", "./resources/metadata", "The directory containing the step metadata. Default points to \\'resources/metadata\\'.")
 	flag.StringVar(&docTemplatePath, "docuDir", "./documentation/docs/steps/", "The directory containing the docu stubs. Default points to \\'documentation/docs/steps/\\'.")
+	flag.StringVar(&customLibraryStepFile, "customLibraryStepFile", "", "")
+
 	flag.Parse()
 
 	fmt.Println("using Metadata Directory:", metadataPath)
 	fmt.Println("using Documentation Directory:", docTemplatePath)
 
+	if len(customLibraryStepFile) > 0 {
+		fmt.Println("Reading custom library step mapping..")
+		content, err := ioutil.ReadFile(customLibraryStepFile)
+		checkError(err)
+		err = yaml.Unmarshal(content, &generator.CustomLibrarySteps)
+		checkError(err)
+		fmt.Println(generator.CustomLibrarySteps)
+	}
+
 	metadataFiles, err := helper.MetadataFiles(metadataPath)
 	checkError(err)
 	err = generator.GenerateStepDocumentation(metadataFiles, generator.DocuHelperData{

pkg/documentation/generator/description.go

@@ -6,6 +6,32 @@ import (
 	"github.com/SAP/jenkins-library/pkg/config"
 )
 
+const configRecommendation = "We recommend to define values of [step parameters](#parameters) via [config.yml file](../configuration.md). In this case, calling the step is reduced to one simple line.<br />Calling the step can be done either via the Jenkins library step or on the [command line](../cli/index.md)."
+
+const (
+	headlineDescription     = "## Description\n\n"
+	headlineUsage           = "## Usage\n\n"
+	headlineJenkinsPipeline = "### Jenkins Pipeline\n\n"
+	headlineCommandLine     = "### Command Line\n\n"
+)
+
+// defaultBinaryName is the name of the local binary that is used for sample generation.
+var defaultBinaryName string = "piper"
+
+// defaultLibraryName is the id of the library in the Jenkins that is used for sample generation.
+var defaultLibraryName string = "piper-lib-os"
+
+// CustomLibrarySteps holds a list of libraries with it's custom steps.
+var CustomLibrarySteps = []CustomLibrary{}
+
+// CustomLibrary represents a custom library with it's custom step names, binary name and library name.
+type CustomLibrary struct {
+	Name        string   `yaml: "name,omitempty"`
+	BinaryName  string   `yaml: "binaryName,omitempty"`
+	LibraryName string   `yaml: "libraryName,omitempty"`
+	Steps       []string `yaml: "steps,omitempty"`
+}
+
 // Replaces the StepName placeholder with the content from the yaml
 func createStepName(stepData *config.StepData) string {
 	return stepData.Metadata.Name + "\n\n" + stepData.Metadata.Description + "\n"
@@ -13,16 +39,27 @@ func createStepName(stepData *config.StepData) string {
 
 // Replaces the Description placeholder with content from the yaml
 func createDescriptionSection(stepData *config.StepData) string {
+	libraryName, binaryName := getNames(stepData.Metadata.Name)
+
 	description := ""
-
-	description += "Description\n\n" + stepData.Metadata.LongDescription + "\n\n"
-
-	description += "## Usage\n\n"
-	description += "We recommend to define values of [step parameters](#parameters) via [config.yml file](../configuration.md). In this case, calling the step is reduced to one simple line.<br />Calling the step can be done either via the Jenkins library step or on the [command line](../cli/index.md).\n\n"
-	description += "### Jenkins pipelines\n\n```groovy\n"
-	description += fmt.Sprintf("%v script: this\n```\n", stepData.Metadata.Name)
-	description += "### Command line\n\n```\n"
-	description += fmt.Sprintf("piper %v\n```\n\n", stepData.Metadata.Name)
+	description += headlineDescription + stepData.Metadata.LongDescription + "\n\n"
+	description += headlineUsage
+	description += configRecommendation + "\n\n"
+	description += headlineJenkinsPipeline
+	description += fmt.Sprintf("```groovy\nlibrary('%s')\n\n%v script: this\n```\n\n", libraryName, stepData.Metadata.Name)
+	description += headlineCommandLine
+	description += fmt.Sprintf("```sh\n%s %v\n```\n\n", binaryName, stepData.Metadata.Name)
 	description += stepOutputs(stepData)
 	return description
 }
+
+func getNames(stepName string) (string, string) {
+	for _, library := range CustomLibrarySteps {
+		for _, customStepName := range library.Steps {
+			if stepName == customStepName {
+				return library.LibraryName, library.BinaryName
+			}
+		}
+	}
+	return defaultLibraryName, defaultBinaryName
+}

pkg/documentation/generator/description_test.go

@@ -0,0 +1,70 @@
+package generator
+
+import (
+	"testing"
+
+	"github.com/SAP/jenkins-library/pkg/config"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCreateStepName(t *testing.T) {
+	tests := []struct {
+		name  string
+		input *config.StepData
+		want  string
+	}{
+		{
+			name: "simple step name section",
+			input: &config.StepData{
+				Metadata: config.StepMetadata{Name: "teststep", Description: "TestDescription"},
+			},
+			want: "teststep\n\nTestDescription\n",
+		},
+	}
+	for _, testcase := range tests {
+		t.Run(testcase.name, func(t *testing.T) {
+			assert.Equal(t, testcase.want, createStepName(testcase.input))
+		})
+	}
+}
+
+func TestCreateDescriptionSection(t *testing.T) {
+	CustomLibrarySteps = []CustomLibrary{{
+		Name:        "TestLibrary",
+		BinaryName:  "myBinary",
+		LibraryName: "myLibrary",
+		Steps:       []string{"myCustomStep"},
+	}}
+
+	tests := []struct {
+		name  string
+		input *config.StepData
+		want  string
+	}{
+		{
+			name: "simple step description section",
+			input: &config.StepData{
+				Metadata: config.StepMetadata{Name: "teststep", LongDescription: "TestDescription"},
+			},
+			want: headlineDescription + "TestDescription" + "\n\n" +
+				headlineUsage + configRecommendation + "\n\n" +
+				headlineJenkinsPipeline + "```groovy\nlibrary('piper-lib-os')\n\nteststep script: this\n```" + "\n\n" +
+				headlineCommandLine + "```sh\npiper teststep\n```" + "\n\n",
+		},
+		{
+			name: "custom step description section",
+			input: &config.StepData{
+				Metadata: config.StepMetadata{Name: "myCustomStep", LongDescription: "TestDescription"},
+			},
+			want: headlineDescription + "TestDescription" + "\n\n" +
+				headlineUsage + configRecommendation + "\n\n" +
+				headlineJenkinsPipeline + "```groovy\nlibrary('myLibrary')\n\nmyCustomStep script: this\n```" + "\n\n" +
+				headlineCommandLine + "```sh\nmyBinary myCustomStep\n```" + "\n\n",
+		},
+	}
+	for _, testcase := range tests {
+		t.Run(testcase.name, func(t *testing.T) {
+			assert.Equal(t, testcase.want, createDescriptionSection(testcase.input))
+		})
+	}
+}