Jenkinfile库方法文档

Question

如何在API调用中添加文档？

我在SCM中创建了以下库函数。它通过Jenkins方法连接，并且工作正常。现在，我需要添加文档，以使其显示在* / pipeline-syntax / globals部分中。 在我的vars/sayHello.groovy中，我具有以下签名：

#!groovy
/**
 *  this says hello
 * @param name to greet
**/
def call(String name) {

我已经用Javadoc语法尝试过，但是似乎不是解决方案。 我应该怎么做才能使文档进入Jenkins视图？例如：

Answer 1

这实际上是个晦涩难懂的地方，您必须四处寻找以找到它，然后进行实验以使其运行。如果您查看共享库的文档，然后向下滚动到directory structure，则会看到一行显示：

  

每个.groovy文件的基本名称应该是一个Groovy（〜Java）标识符，通常是camelCased。匹配的.txt（如果存在）可以包含通过系统配置的标记格式设置器处理的文档（因此可能确实是HTML，Markdown等，尽管需要txt扩展名）。

这意味着您需要相应的vars/sayHello.txt。创建该文件后，它将用于在您要查找的位置（https://<jenkins_host>/job/<your_job>/pipeline-syntax/globals）生成文档。如文档所述，您可以在文件中使用Markdown或HTML之类的标记语言，但是扩展名必须为.txt，并且必须具有相同的基本名称。

这里还有两个警告。第一个是在显示文档之前，您必须至少运行一个加载了共享库的管道。第二个方法与原始说明一样晦涩：您必须重新启动（甚至可能重新启动）Jenkins实例。

一旦满足了所有这些要求（老实说，我一直坚持重启要求，直到用户“ missedone”在我的Jenkins库的Github问题跟踪器上向我提到了它），然后将显示您想要的文档。

需要额外注意的是，这些文档文件可以是到库中其他位置（例如sayHello.txt --> ../docs/sayHello.md）的符号链接，因为这样做可以正常工作。