From b16f0428e1d1132d02d05b8153daa9e713f2d379 Mon Sep 17 00:00:00 2001 From: Christopher Fenner <26137398+CCFenner@users.noreply.github.com> Date: Wed, 30 Sep 2020 15:02:00 +0200 Subject: [PATCH] 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 | 13 ++++ pkg/documentation/generator/description.go | 55 ++++++++++++--- .../generator/description_test.go | 70 +++++++++++++++++++ 3 files changed, 129 insertions(+), 9 deletions(-) create mode 100644 pkg/documentation/generator/description_test.go diff --git a/pkg/documentation/generator.go b/pkg/documentation/generator.go index 5f14ecc65..5c305d9be 100644 --- a/pkg/documentation/generator.go +++ b/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{ diff --git a/pkg/documentation/generator/description.go b/pkg/documentation/generator/description.go index 013fcc331..c8970c49c 100644 --- a/pkg/documentation/generator/description.go +++ b/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.
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.
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 +} diff --git a/pkg/documentation/generator/description_test.go b/pkg/documentation/generator/description_test.go new file mode 100644 index 000000000..ca551f772 --- /dev/null +++ b/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)) + }) + } +}