jenkins - Jenkinsfile 库方法文档

Question

如何向 API 调用添加文档？

我在 SCM 中创建了以下库函数。它通过 Jenkins 方法连接，效果很好。现在我需要添加文档，以便它显示在 */pipeline-syntax/globals 部分中。在我的 vars/sayHello.groovy 中，我有以下签名:

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

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

Answer 1

这实际上相当晦涩，你必须四处挖掘才能找到它，然后进行实验才能使其发挥作用。如果您查看共享库的文档，然后向下滚动到 directory structure ，然后你会看到一行内容:

The basename of each .groovy file should be a Groovy (~ Java) identifier, conventionally camelCased. The matching .txt, if present, can contain documentation, processed through the system’s configured markup formatter (so may really be HTML, Markdown, etc., though the txt extension is required).

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

这里还有两个额外的警告。首先，在显示文档之前，您必须运行至少一个加载了共享库的管道。第二个与如何执行此操作的原始说明一样晦涩:您必须重新启动(甚至可能重新启动)Jenkins 实例。

一旦这些要求全部得到满足(老实说，我一直坚持重启要求，直到用户“missedone”在我的 Jenkins 库的 Github 问题跟踪器上向我提到它)，然后您想要的文档就会显示。

还有一点需要注意的是，这些文档文件可以是指向库中其他位置的符号链接(symbolic link)(例如 sayHello.txt --> ../docs/sayHello.md )，正如我所做的那样，它有效。