gradlegroovygroovydoc

Generate groovydoc without compiling Groovy sources using Gradle

I am trying to generate docs from some groovy code but Gradle fails because it can't import the dependencies when trying to compile the code. This is expected since that code needs to run in a specific context before those dependencies are available. I don't know why it's even trying to compile the code when it seems that it should just be parsing the source to extract the docs but that's a side issue.

My build.gradle:

apply plugin: 'groovy'

repositories {
    mavenCentral();
}

dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.4.5'
}


sourceSets {
    main {
        groovy {
            srcDirs = ['src/org/mysource']
        }
    }
}

I've tried various things such as exclude in both the groovyCompile and CompileGroovy tasks but that made no difference. I'm not able to provide the dependencies in this context. Other suggestions welcome. Bonus points for anyone who can identify a workable solution for using asciidoc to document groovy, which I also failed to achieve.

Solution

  • You have two options to disable :compileGroovy while running groovydoc task. A short example first. I have a Groovy Gradle project where I have introduced some change that makes its compilation fail:

    gradle groovydoc

    Output:

    > Task :compileGroovy FAILED
startup failed:
/home/wololock/workspace/upwork/jenkins-continuous-delivery-pipeline/src/com/upwork/util/MapUtils.groovy: 29: [Static type checking] - Cannot find matching method com.upwork.util.MapUtils#merge(V, java.lang.Object). Please check if the declared type is right and if the method exists.
 @ line 29, column 56.
    = result[k] instanceof Map ? merge(resu
                                 ^
1 error

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':compileGroovy'.
> Compilation failed; see the compiler error output for details.

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 4s
1 actionable task: 1 executed

    Now let's take a closer look to an options that allow me to generate groovydoc without compiling this source.


    1. Disable compileGroovy from command-line

    You can use -x switch to disable compileGroovy when you run groovydoc Gradle task:

    gradle clean groovydoc -x compileGroovy

    Output:

    > Task :groovydoc 
Trying to override old definition of task fileScanner

BUILD SUCCESSFUL in 2s
2 actionable tasks: 2 executed


    2. Disable compileGroovy in build.gradle

    If you don't want to use -x switch and you expect compileGroovy task to be disabled whenever you run groovydoc then you can disable compileGroovy by modifying task graph in build.gradle:

    gradle.taskGraph.whenReady { graph ->
  if (graph.hasTask(':groovydoc')) {
    compileGroovy.enabled = false
  }
}

    Simply add it somewhere in your build.gradle file. Now when you execute:

    gradle groovydoc

    the task compileGroovy will be disabled and source code wont get compiled.

    > Task :groovydoc 
Trying to override old definition of task fileScanner

BUILD SUCCESSFUL in 2s
2 actionable tasks: 2 executed