如何从 jenkins 全局库生成 groovydoc

Question

我有一个jenkins global library，我想记录它。我想使用 groovydoc。

该库包含类和全局变量

src/<package-name>
vars

为类生成文档没问题：

groovydoc -sourcepath src -d doc 'main.pipeline' '*.groovy'

但是如何为变量生成文档呢？

Answer 1

为了确保在正确的包中报告所有内容，而不必枚举所有包，我使用了：

mkdir -p doc/

groovydoc -d doc -private -nomainforscripts -sourcepath src:vars \
    $(find src/ vars/ -name \*.groovy -printf '%P\n')

这个咒语说服 Groovydoc 正确地获取软件包，而无需我繁琐地列出所有软件包，这是主要挑战。

如果您的find 没有-printf，请将-printf '%P\n' 替换为| cut -d '/' -f 2-。效果是一样的；去掉前面的src/ 或vars/。

Answer 2

Maven 解决方案：

<plugin>
    <groupId>org.codehaus.gmavenplus</groupId>
    <artifactId>gmavenplus-plugin</artifactId>
    <version>1.7.1</version>
    <executions>
      <execution>
        <goals>
          <goal>addSources</goal>
          <goal>addTestSources</goal>
          <goal>compile</goal>
          <goal>compileTests</goal>
          <goal>groovydoc</goal>
        </goals>
      </execution>
    </executions>
    <configuration>
      <sources>
        <source>
          <directory>${project.basedir}/vars</directory>
          <includes>
            <include>**/*.groovy</include>
          </includes>
        </source>
        <source>
          <directory>${project.basedir}/src</directory>
          <includes>
            <include>**/*.groovy</include>
          </includes>
        </source>
      </sources>
      <testSources>
        <testSource>
          <directory>${project.basedir}/test</directory>
          <includes>
            <include>**/*.groovy</include>
          </includes>
        </testSource>
      </testSources>
      <docTitle>Jenkins Shared Libs</docTitle>
      <header>${titre}</header>
      <footer>${titre}</footer>
      <windowTitle>${titre}</windowTitle>
    </configuration>
  </plugin>

Answer 3

今天在工作中遇到了同样的问题，很遗憾现在无法尝试我的解决方案，但尝试使用包含src 和vars 的目录作为sourcepath。然后你可以像这样在你的命令中引用你的src 和vars 子目录：

groovydoc -sourcepath [PATH_TO_YOUR_LIB] -d doc src\ vars\

如果这不起作用，请尝试像这样单独引用每个包：

groovydoc -sourcepath [PATH_TO_YOUR_LIB] -d doc src\org.foo.some_package src\org.foo.some_other_package vars\

或者，作为一种解决方法，您可以使用 IntelliJ IDE 及其“生成 GroovyDoc...”工具：

1. 启动 IntelliJ 并打开任何 Groovy 项目（如果没有现有项目，则创建一个新项目）
2. 来自菜单栏Tools > Generate GroovyDoc...
3. 选择包含 jenkins 管道库的源路径为Input directory（同时包含src 和vars）和任何路径为Output directory
4. 按Start
5. GroovyDoc 应该在指定的Output directory

Answer 4

我也面临同样的问题。我只需要一个参数概述。我知道有很多改进空间，但适用于我的用例：

import groovy.io.FileType
import java.util.regex.*;

class DocGenerator {
    String run(String root_path) {


        def list = []

        def dir = new File(root_path)
        dir.eachFileRecurse(FileType.FILES) { file ->
            if (file.name.contains("groovy"))
                list << file
        }

        String output = "| Method | Doc |\n"
        output += "| ------ | ------ |\n"

        list.each {
            output += "| ${it.name.replace(".groovy","")} | ${getComment(it.text.replace("\r\n","<br>"))} |\n"
        }

        println(output)
        return output
    }

    String getComment(String txt) {


        String re1 = "(\\/\\*[\\d\\D]*?\\*\\/)";    // C Comment 1
        String re2 = ".*?";    // Non-greedy match on filler
        String re3 = "def";    // Word 1
        String re4 = ".*?";    // Non-greedy match on filler
        String re5 = "call";    // Word 2

        Pattern p = Pattern.compile(re1 + re2 + re3 + re4 + re5, Pattern.CASE_INSENSITIVE | Pattern.DOTALL);
        Matcher m = p.matcher(txt);
        if (m.find()) {
            String ccomment1 = m.group(1);

            return m.group(1)
        }

    }

}

app = new DocGenerator()
app.run "C:\\Git\\JenkinsSharedLibrary\\vars"

我的输出旨在添加到 readme.md。但我想你明白了

Answer 5

什么对我有用：

groovydoc -d docs -sourcepath "src;." my.package vars

将 vars 中的所有内容导出为 DefaultPackage 和 src 文件夹中包含的 my.package。