github.com/ouraigua/jenkins-library@v0.0.0-20231028010029-fbeaf2f3aa9b/pkg/documentation/generator/description.go (about) 1 package generator 2 3 import ( 4 "fmt" 5 6 "github.com/SAP/jenkins-library/pkg/config" 7 ) 8 9 const configRecommendation = "We recommend to define values of [step parameters](#parameters) via [.pipeline/config.yml file](../configuration.md).<br />In this case, calling the step is essentially reduced to defining the step name.<br />Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line." 10 11 const ( 12 headlineDescription = "## Description\n\n" 13 headlineUsage = "## Usage\n\n" 14 headlineJenkinsPipeline = " === \"Jenkins\"\n\n" 15 headlineCommandLine = " === \"Command Line\"\n\n" 16 headlineAzure = " === \"Azure\"\n\n" 17 spacingTabBox = " " 18 ) 19 20 // defaultBinaryName is the name of the local binary that is used for sample generation. 21 var defaultBinaryName string = "piper" 22 23 // defaultLibraryName is the id of the library in the Jenkins that is used for sample generation. 24 var defaultLibraryName string = "piper-lib-os" 25 26 // CustomLibrarySteps holds a list of libraries with it's custom steps. 27 var CustomLibrarySteps = []CustomLibrary{} 28 29 // CustomLibrary represents a custom library with it's custom step names, binary name and library name. 30 type CustomLibrary struct { 31 Name string `yaml: "name,omitempty"` 32 BinaryName string `yaml: "binaryName,omitempty"` 33 LibraryName string `yaml: "libraryName,omitempty"` 34 Steps []string `yaml: "steps,omitempty"` 35 } 36 37 // Replaces the StepName placeholder with the content from the yaml 38 func createStepName(stepData *config.StepData) string { 39 return "# " + stepData.Metadata.Name + "\n\n" + stepData.Metadata.Description + "\n" 40 } 41 42 // Replaces the Description placeholder with content from the yaml 43 func createDescriptionSection(stepData *config.StepData) string { 44 libraryName, binaryName := getNames(stepData.Metadata.Name) 45 46 description := "" 47 description += headlineDescription + stepData.Metadata.LongDescription + "\n\n" 48 description += headlineUsage 49 description += configRecommendation + "\n\n" 50 description += `!!! tip ""` + "\n\n" 51 // add Jenkins-specific information 52 description += headlineJenkinsPipeline 53 description += fmt.Sprintf("%v```groovy\n", spacingTabBox) 54 description += fmt.Sprintf("%vlibrary('%s')\n\n", spacingTabBox, libraryName) 55 description += fmt.Sprintf("%v%v script: this\n", spacingTabBox, stepData.Metadata.Name) 56 description += fmt.Sprintf("%v```\n\n", spacingTabBox) 57 58 // add Azure-specific information if activated 59 if includeAzure { 60 description += headlineAzure 61 description += fmt.Sprintf("%v```\n", spacingTabBox) 62 description += fmt.Sprintf("%vsteps:\n", spacingTabBox) 63 description += fmt.Sprintf("%v - task: piper@1\n", spacingTabBox) 64 description += fmt.Sprintf("%v name: %v\n", spacingTabBox, stepData.Metadata.Name) 65 description += fmt.Sprintf("%v inputs:\n", spacingTabBox) 66 description += fmt.Sprintf("%v stepName: %v\n", spacingTabBox, stepData.Metadata.Name) 67 description += fmt.Sprintf("%v```\n\n", spacingTabBox) 68 } 69 70 // add command line information 71 description += headlineCommandLine 72 description += fmt.Sprintf("%v```sh\n", spacingTabBox) 73 description += fmt.Sprintf("%v%s %v\n", spacingTabBox, binaryName, stepData.Metadata.Name) 74 description += fmt.Sprintf("%v```\n\n", spacingTabBox) 75 76 description += stepOutputs(stepData) 77 return description 78 } 79 80 func getNames(stepName string) (string, string) { 81 for _, library := range CustomLibrarySteps { 82 for _, customStepName := range library.Steps { 83 if stepName == customStepName { 84 return library.LibraryName, library.BinaryName 85 } 86 } 87 } 88 return defaultLibraryName, defaultBinaryName 89 }