8

I have a jenkins global library and I want to document it. I want to use groovydoc.

The library contains classes and global vars

src/<package-name>
vars

Generating documentation for the classes is no problem:

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

But how can I generate documentation for the vars?

Vadim Kotov
  • 8,084
  • 8
  • 48
  • 62
Nathan
  • 7,099
  • 14
  • 61
  • 125

5 Answers5

4

To ensure everything was reported in the right packages, without having to enumerate all the packages, I used:

mkdir -p doc/

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

This incantation convinces Groovydoc to get the packages right without requiring me to tediously list them all, which is the main challenge.

If your find doesn't have -printf, replace -printf '%P\n' with | cut -d '/' -f 2-. The effect is the same; strip the leading src/ or vars/.

Craig Ringer
  • 307,061
  • 76
  • 688
  • 778
1

What worked for me:

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

Exports everything in vars as DefaultPackage and my.package contained in the src folder.

Fabian Braun
  • 3,612
  • 1
  • 27
  • 44
1

Maven solution:

<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>
Alex Myers
  • 6,196
  • 7
  • 23
  • 39
Fabricio Boechat
  • 11
  • 1
0

Had the same problem at work today and sadly can't try my solution now, but try using the directory containing both src and vars as sourcepath. Then you can reference your src and vars subdirectories in your command like this:

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

If that doesnt work, try referencing each package seperately somewhat like this:

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

Alternatively, or as a workaround, you could use the IntelliJ IDE and its "Generate GroovyDoc..."-Tool:

  1. Start IntelliJ and open any Groovy project (create a new one if there isnt an existing one)
  2. From the menu bar Tools > Generate GroovyDoc...
  3. Choose your source path containing your jenkins pipeline library as Input directory (containing both src and vars) and any path as Output directory
  4. Press Start
  5. GroovyDoc should be in the specified Output directory
Adrian Kuper
  • 149
  • 6
  • 1
    The output I get is completely unusable. The structure of the shared libraries is not standard groovy. For example the files in /vars are not classes but just methods listed in a file. – herm Oct 10 '17 at 09:59
0

i was facing the same issue. i just needed an overview with parameters. I know there is lots of space for improvement, but works for my usecase:

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"

My output was intended to be added to an readme.md. But i think you get the point

eXpire 163
  • 1
  • 1