We already saw that we can open a repository with global pipeline libraries and consult the functions to find out what they do. While the developer in me prefers that option, many might find it too complicated and might prefer something more "non-developer friendly". Fortunately, there is an alternative way to document and consult libraries.
Let's go back to the forked repository with the libraries.
1 open
"https://github.com/$GH_USER/jenkins-shared-libraries/tree/master/vars"
If you pay closer attention, you'll notice that all Groovy files with names that start with k8s have an accompanying txt file. Let's take a closer look at one of them.
1 curl "https://raw.githubusercontent.com/$GH_USER/jenkins-shared-
libraries/master/vars/k8sBuildImageBeta.txt"
The output is as follows.
## Builds a Docker image with a beta release
The image is tagged with the **build display name** suffixed with the branch name
**Arguments:**
* **image**: the name of the Docker image (e.g. `vfarcic/go-demo-3`).
Requirements:
* A node with Docker
* Docker Hub credentials with the ID **docker**
Do not get confused with txt extension. Documentation can be written not only in plain text but also as HTML or Markdown. As you can see, I chose the latter. It is entirely up to you how you'll write corresponding documentation of a function. There is no prescribed formula. The only thing that matters is that the name of the txt file is the same as the name of the groovy function. The only difference is in the extension.
But, how do we visualize those helper files, besides visiting the repository where they reside? Before I answer that question, we'll make a slight change to Jenkins' security configuration.
1 open "http://$JENKINS_ADDR/configureSecurity/"
Please scroll down to the Markup Formatter section and change the value to PegDown. Click the Apply button to persist the change. From now on, Jenkins will format everything using the Markdown parser. Since our helper files are also written in Markdown, we should be able to visualize them correctly.
Let's find the documentation of the libraries.
1 open "http://$JENKINS_ADDR/job/go-demo-3/"
We are in the old view of the job we created short while ago. If you look at the left-hand menu, you'll see the link Pipeline Syntax. Click it.
The screen we're looking at contains quite a few useful links. There's Snippet Generator that we can use to generate code for each of the available steps. Declarative Directive Generator generates the code specific to Declarative Pipeline syntax that we're not (yet) using. I'll let you explore those and the other links at your own leisure. The one we're interested right now is the Global Variables Reference link. Please click it.
Inside the Global Variable Reference screen are all the variables and functions we can use. We're interested in those with names starting with k8s. Please scroll down until you find them.
You'll see that .txt files are nicely formatted and available to anyone interested how to use our functions.
