allow markdown and html files for documentation of library steps

pom.xml

@@ -118,7 +118,15 @@
             <groupId>org.jenkins-ci.plugins</groupId>
             <artifactId>script-security</artifactId>
         </dependency>
-
+        <dependency>
+            <groupId>io.jenkins.plugins</groupId>
+            <artifactId>markdown-formatter</artifactId>
+            <version>95.v17a_965e696ee</version>
+        </dependency>
+        <dependency>
+            <groupId>org.jenkins-ci.plugins</groupId>
+            <artifactId>antisamy-markup-formatter</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.jenkins-ci.plugins</groupId>
             <artifactId>variant</artifactId>

src/main/java/org/jenkinsci/plugins/workflow/cps/global/HelpFormatter.java

@@ -0,0 +1,104 @@
+package org.jenkinsci.plugins.workflow.cps.global;
+
+import hudson.Extension;
+import hudson.ExtensionPoint;
+import hudson.markup.MarkupFormatter;
+import hudson.markup.RawHtmlMarkupFormatter;
+import io.jenkins.plugins.MarkdownFormatter;
+import java.io.File;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import jenkins.model.Jenkins;
+import org.apache.commons.io.FileUtils;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.NoExternalUse;
+
+/**
+ * Formatter for the help of a library step.
+ * Allows to use markdown and html for the help. Avoids using the globally configured formatter
+ * that might not fit.
+ */
+@Restricted(NoExternalUse.class)
+public abstract class HelpFormatter implements ExtensionPoint {
+
+    public boolean isApplicable(String file) {
+        return getFile(file).exists();
+    }
+
+    private File getFile(String file) {
+        return new File(file + getExtension());
+    }
+    protected abstract String getExtension();
+
+    protected abstract MarkupFormatter getFormatter();
+
+    public final String translate(String file) throws IOException {
+        return "<div class=\"library-step-help\">\n" +
+                getFormatter().translate(readFile(file)) +
+                "</div>";
+    }
+
+    private String readFile(String file) throws IOException {
+        // Util.escape translates \n but not \r, and we do not know what platform the library will
+        // be checked out on:
+        return FileUtils.readFileToString(getFile(file), StandardCharsets.UTF_8).replace("\r\n", "\n");
+    }
+
+    public static List<HelpFormatter> all() {
+        return Jenkins.get().getExtensionList(HelpFormatter.class);
+    }
+
+    @Extension(ordinal = 99999)
+    public static class MarkDown extends HelpFormatter {
+
+        private static final String EXTENSION = ".md";
+
+        @Override
+        protected String getExtension() {
+            return EXTENSION;
+        }
+
+        @Override
+        protected MarkupFormatter getFormatter() {
+            return new MarkdownFormatter();
+        }
+    }
+
+    /**
+     * formatter for html files based on the OWASP formatter
+     */
+    @Extension(ordinal = 50000)
+    public static class HtmlFormatter extends HelpFormatter {
+
+        private static final String EXTENSION = ".html";
+
+        @Override
+        protected String getExtension() {
+            return EXTENSION;
+        }
+
+        protected MarkupFormatter getFormatter() {
+            return new RawHtmlMarkupFormatter(true);
+        }
+    }
+
+    /**
+     * Formatter for txt files, uses the globally configured formatter
+     */
+    @Extension(ordinal = -99999)
+    public static class Default extends HelpFormatter {
+
+        private static final String EXTENSION = ".txt";
+
+        @Override
+        protected String getExtension() {
+            return EXTENSION;
+        }
+
+        @Override
+        protected MarkupFormatter getFormatter() {
+            return Jenkins.get().getMarkupFormatter();
+        }
+    }
+}

src/main/java/org/jenkinsci/plugins/workflow/cps/global/UserDefinedGlobalVariable.java

@@ -1,8 +1,6 @@
 package org.jenkinsci.plugins.workflow.cps.global;
 
 import groovy.lang.Binding;
-import java.nio.charset.StandardCharsets;
-import org.apache.commons.io.FileUtils;
 import org.codehaus.groovy.control.MultipleCompilationErrorsException;
 import org.jenkinsci.plugins.workflow.cps.CpsCompilationErrorsException;
 import org.jenkinsci.plugins.workflow.cps.CpsScript;
@@ -11,9 +9,7 @@
 
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
-import java.io.File;
 import java.io.IOException;
-import jenkins.model.Jenkins;
 
 /**
  * Global variable backed by user-supplied script.
@@ -22,10 +18,10 @@
  */
 // not @Extension because these are instantiated programmatically
 public class UserDefinedGlobalVariable extends GlobalVariable {
-    private final File help;
+    private final String help;
     private final String name;
 
-    public UserDefinedGlobalVariable(String name, File help) {
+    public UserDefinedGlobalVariable(String name, String help) {
         this.name = name;
         this.help = help;
     }
@@ -69,12 +65,12 @@ public Object getValue(@NonNull CpsScript script) throws Exception {
      * Loads help from user-defined file, if available.
      */
     public @CheckForNull String getHelpHtml() throws IOException {
-        if (!help.exists())     return null;
-
-        return Jenkins.get().getMarkupFormatter().translate(
-            FileUtils.readFileToString(help, StandardCharsets.UTF_8).
-            // Util.escape translates \n but not \r, and we do not know what platform the library will be checked out on:
-            replace("\r\n", "\n"));
+        for (HelpFormatter formatter: HelpFormatter.all()) {
+            if (formatter.isApplicable(help)) {
+                return formatter.translate(help);
+            }
+        }
+        return null;
     }
 
     @Override

src/main/java/org/jenkinsci/plugins/workflow/libs/LibraryAdder.java

@@ -358,7 +358,7 @@ private static String readResource(FilePath file, @CheckForNull String encoding)
             List<GlobalVariable> vars = new ArrayList<>();
             for (LibraryRecord library : action.getLibraries()) {
                 for (String variable : library.variables) {
-                    vars.add(new UserDefinedGlobalVariable(variable, new File(run.getRootDir(), "libs/" + library.getDirectoryName() + "/vars/" + variable + ".txt")));
+                    vars.add(new UserDefinedGlobalVariable(variable, new File(run.getRootDir(), "libs/" + library.getDirectoryName() + "/vars/" + variable).getAbsolutePath()));
                 }
             }
             return vars;

src/main/java/org/jenkinsci/plugins/workflow/libs/SCMBasedRetriever.java

@@ -210,7 +210,7 @@ protected final void doRetrieve(String name, boolean changelog, @NonNull SCM scm
                 }
                 // Cannot add WorkspaceActionImpl to private CpsFlowExecution.flowStartNodeActions; do we care?
                 // Copy sources with relevant files from the checkout:
-                lease.path.child(libraryPath).copyRecursiveTo("src/**/*.groovy,vars/*.groovy,vars/*.txt,resources/", excludes, target);
+                lease.path.child(libraryPath).copyRecursiveTo("src/**/*.groovy,vars/*.groovy,vars/*.txt,vars/*.md,vars/*.html,resources/", excludes, target);
             }
         }
     }

src/test/java/org/jenkinsci/plugins/workflow/libs/LibraryAdderTest.java

@@ -245,7 +245,25 @@ public class LibraryAdderTest {
         r.assertLogContains("something special", b);
         GlobalVariable var = GlobalVariable.byName("myecho", b);
         assertNotNull(var);
-        assertEquals("Says something very special!", ((UserDefinedGlobalVariable) var).getHelpHtml());
+        assertEquals("<div class=\"library-step-help\">\nSays something very special!</div>", ((UserDefinedGlobalVariable) var).getHelpHtml());
+    }
+
+    @Test public void globalVariableWithMarkdown() throws Exception {
+        sampleRepo.init();
+        sampleRepo.write("vars/myecho.groovy", "def call() {echo 'something special'}");
+        sampleRepo.write("vars/myecho.md", "# Says something very special!");
+        sampleRepo.git("add", "vars");
+        sampleRepo.git("commit", "--message=init");
+        GlobalLibraries.get().setLibraries(Collections.singletonList(
+                new LibraryConfiguration("echo-utils",
+                        new SCMSourceRetriever(new GitSCMSource(null, sampleRepo.toString(), "", "*", "", true)))));
+        WorkflowJob p = r.jenkins.createProject(WorkflowJob.class, "p");
+        p.setDefinition(new CpsFlowDefinition("@Library('echo-utils@master') import myecho; myecho()", true));
+        WorkflowRun b = r.buildAndAssertSuccess(p);
+        r.assertLogContains("something special", b);
+        GlobalVariable var = GlobalVariable.byName("myecho", b);
+        assertNotNull(var);
+        assertEquals("<div class=\"library-step-help\">\n<h1>Says something very special!</h1>\n</div>", ((UserDefinedGlobalVariable) var).getHelpHtml());
     }
 
     @Test public void dynamicLibraries() throws Exception {