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  }