CODEWITHSUNDEEP
jenkinsjenkins-pipelinejenkins-shared-librariesgroovydoc
Nathan
Nathan

Reputation: 7709

How to generate groovydoc from jenkins global library

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?

Upvotes: 8

Views: 3002

Answers (5)

Fabricio Boechat
Fabricio Boechat

Reputation: 11

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>

Upvotes: 1

Craig Ringer
Craig Ringer

Reputation: 324681

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/.

Upvotes: 5

Fabian Braun
Fabian Braun

Reputation: 3940

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.

Upvotes: 1

eXpire 163
eXpire 163

Reputation: 1

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

Upvotes: 0

Adrian Kuper
Adrian Kuper

Reputation: 149

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

Upvotes: 0

Related Questions