New generation Asciidoctor Gradle plugins

General:
- Use 'base' plugin model for Asciidoctor plugins.
- Only support Gradle 4.0+.
- Only support JDK8+.
- For Gradle 4.5+ migration messages are controlled via `--warning-mode`.
- For Gradle 4.0-4.4 migration messages are controlled via `--info`.
- Additional text will be displayed on Gradle Plugin Portal for during
  alpha & beta releases.
- Compatibility testing has been added and initialy against Gradle
  versions 4.0, 4.3 & 4.6. (For JDK10 only test against 4.7).
- Codenarc settings has been updated to find configuration from within
  subprojects.
- Updated license headers to include 2018.
- Integration tests utilises an offline Ivy repository (via Ivypot plugin)
  to reduce bandwith usage and test time.
- AsciidoctorJ, GroovyDSL etc. versions are defined in code and read by the
  build script. This provides one point of definition and ensure that code
  can have appropriate default versions.

New generation plugins and tasks:
- New (JVM) AsciidoctorJ extension can be added to both project & tasks.
  Extension in task can be used to override global settings from the
  project extension. It takes into account some of the ideas @manuelprinz
  had for asciidoctor#231 for is much more extensive.
- Extension has support for Asciidoctor verbose mode (asciidoctor#233).
  If `verboseMode` is set then a temporary file will be created and made
  part of Asciidoctor `requires`.
- JRuby version can be controlled at both project and task level. If no
  version is specified at either level, the default JRuby version that
  AsciidoctorJ depends on will be used.
- GroovyDSL extensions are now registered eitehr on the project extension
  or the task extensions. The extensions are only loaded within a worker
  instance. The asciidoctor task is unloaded at the end of the worker and
  with it the extensions. (asciidoctor#166)
- AsciidoctorTask differentitates between top-level sources, secondary
  sources and resources in order to have a better idea of being
  out-of-date. (asciidoctor#185)
- It is possible to control whether resources should be copied or not. This
  allows a build to better deal with a backend such as PDF, which do not
  need resources to be copied.
- It is possible to perform the conversion from an intermediate working
  directory, which allows for a source directory to be kept pristine from
  intermediate artifacts generated from extensions such as ditaa.
- Using a worker approach for running Asciidoctor instances. (asciidoctor#220)
- Asciidoctor tasks can be configured to run AsciidoctorJ conversions in
  or out of process. Even when running in process AsciidoctorJ will be on
  an isolated classpath.
- Tasks support parallel mode which will run each backend (or in the case
  of Epub, each output format) in a separate worker. This behevaiour can
  be turned off in which case only one Asciidoctor instance is used to run
  all conversions in sequence.
- For cases where Gradle's idea of supplementing the classpath for workers
  do fail, there is a special `inProcess = JAVA_EXEC` that will run the
  conversion out of process, albeit less efficient than an out-of-process
  worker.
- Due to Gradle API classpath leakage, builds with Gradle 4.0-4.2 will
  always run in `JAVA_EXEC` mode to prevent issues.
- `AsciidoctorJPdf` plugin has been added which adds a single
  `asciidoctorPdf` task and configures it accordingly to PDF behaviour.
  It also sets a default version of the `asciidoctorj-pdf` dependency.
- Backends and separateOutputDirs are configured via an outputOptions
  closure or action.
- `AsciidoctorJEpub` plugin has been added which adds a single
  `asciidoctorEpub` task and configures it accordingly to EPUB behaviour.
  It also sets a default version of the `asciidoctorj-epub` dependency.
- Epub output formats can be set via the `ebookFormats` method.
- Additional Kindlegen plugin which is invoked by EPUB for when the format
  is KF8. The plugin will bootstrap kindlegen on all supported platforms.
- Work around gradle/gradle#3698 and Xerces API
  clash by running EPub conversions using `inProcess = JAVA_EXEC`.
- All methods on the new task classes that take closures as parameters now
  also have equivalent Action parameters (asciidoctor#236).
- All new tasks are supportd by integration tests and compatibility tests. (asciidoctor#180)

Known issues:
- Intermittent failsures in tests related to bad file descriptor. Could be
  similar to asciidoctor/asciidoctorj#442.
- EPUB3 + KF8 in one task (PendingFeature). Both formats in one task is
  currently failing. The exact failure message depends on which order
  (KF8+EPUB3 or EPUB3+KF8) the conversion takes place in.

Backwards compatibility and migration:
- Legacy code moved to 'org.asciidoctor.gradle.compat' package,
  but get AsciidoctorTask in same package for compatibility purpose.
- Renamed AsciidoctorPlugin to AsciidoctorCompatibilityPlugin.
- Legacy plugin cannot be used with other Asciidoctor plugins within
  the same project.
- Existing 1.5.x deprecated methods has been removed from legacy
  AsciidoctorTask.

.travis.yml

@@ -4,18 +4,19 @@ install: true
 
 cache:
     directories:
-        - $HOME/.m2
         - $HOME/.gradle
+        - .gradle/
 
 before_script:
     - ./gradlew --version
 
 script:
-    - TERM=dumb ./gradlew build jacocoTestReport
+    - ./gradlew -i --console=plain --warning-mode=all build jacocoTestReport
 
 jdk:
     - oraclejdk8
     - oraclejdk9
+    - oraclejdk10
 
 after_success:
     - ./gradlew coveralls

appveyor.yml

@@ -13,9 +13,11 @@ install:
   - echo %PATH%
   - gradlew.bat --version
 build_script:
-  - gradlew.bat -u -i clean assemble
+  - gradlew.bat --console=plain --warning-mode=all -i clean assemble
 test_script:
-  - gradlew.bat -u -i -S check
+  - gradlew.bat --console=plain -i -s check
+after_test:
+  - gradlew.bat --stop
 cache:
   - .gradle
   - C:\Users\appveyor\.gradle

asciidoctor-gradle-base/build.gradle

@@ -0,0 +1,26 @@
+
+/*
+ * Copyright 2013-2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+gradlePlugin {
+    plugins {
+        asciidoctorBasePlugin {
+            id = 'org.asciidoctor.org.asciidoctor.base'
+            implementationClass = 'org.asciidoctor.gradle.base.AsciidoctorBasePlugin'
+            description = 'Base plugin for AsciidoctorJ & AscidoctorJS plugins'
+        }
+    }
+}

asciidoctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/AsciidoctorBasePlugin.groovy

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2013-2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.asciidoctor.gradle.base
+
+import groovy.transform.CompileStatic
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+
+/**
+ * @since 1.6.0
+ */
+@CompileStatic
+class AsciidoctorBasePlugin implements Plugin<Project> {
+
+    void apply(Project project) {
+        project.with {
+            apply plugin : 'base'
+        }
+    }
+}

asciidoctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/SafeMode.groovy

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2013-2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.asciidoctor.gradle.base
+
+import groovy.transform.CompileStatic
+
+/** Describes Asciidoc sefty modes.
+ *
+ * (This has been ported to the plugin from the AscidoctorJ code base).
+ *
+ * @author Alex Soto
+ * @author Schalk W. Cronjé
+ *
+ */
+@CompileStatic
+enum SafeMode {
+
+    /**
+     * A safe mode level that disables any of the security features enforced by Asciidoctor (Ruby is still subject to
+     * its own restrictions).
+     */
+    UNSAFE(0),
+    /**
+     * A safe mode level that closely parallels safe mode in AsciiDoc. This value prevents access to files which reside
+     * outside of the parent directory of the source file and disables any macro other than the include::[] macro.
+     */
+    SAFE(1),
+    /**
+     * A safe mode level that disallows the document from setting attributes that would affect the rendering of the
+     * document, in addition to all the security features of SafeMode::SAFE. For instance, this level disallows changing
+     * the backend or the source-highlighter using an attribute defined in the source document. This is the most
+     * fundamental level of security for server-side deployments (hence the name).
+     */
+    SERVER(10),
+    /**
+     * A safe mode level that disallows the document from attempting to read files from the file system and including
+     * the contents of them into the document, in additional to all the security features of SafeMode::SERVER. For
+     * instance, this level disallows use of the include::[] macro and the embedding of binary content (data uri),
+     * stylesheets and JavaScripts referenced by the document.(Asciidoctor and trusted extensions may still be allowed
+     * to embed trusted content into the document).
+     *
+     * Since Asciidoctor is aiming for wide adoption, this level is the default and is recommended for server-side
+     * deployments.
+     */
+    SECURE(20)
+
+    final private int level
+
+    private SafeMode(int level) {
+        this.level = level
+    }
+
+    int getLevel() {
+        this.level
+    }
+
+    static final SafeMode safeMode(int level) {
+        switch(level) {
+            case 0: return UNSAFE
+            case 1: return SAFE
+            case 10: return SERVER
+            default: return SECURE
+        }
+    }
+
+}

asciidoctor-gradle-base/src/main/resources/META-INF/gradle-plugins/org.asciidoctor.base.properties

@@ -0,0 +1,17 @@
+#
+# Copyright 2013-2018 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+implementation-class=org.asciidoctor.gradle.base.AsciidoctorBasePlugin

asciidoctor-gradle-jvm-epub/build.gradle

@@ -0,0 +1,50 @@
+apply from: "${rootProject.projectDir}/gradle/asciidoctorj-versions.gradle"
+
+ext {
+    jrubyFileContent = file("src/intTest/groovy/org/asciidoctor/gradle/jvm/epub/AsciidoctorEpubTaskFunctionalSpec.groovy").readLines()
+
+    jrubyTestVersion = (jrubyFileContent.grep {
+        it =~ /final\s+static\s+String\s+JRUBY_TEST_VERSION\s+=/
+    })[0].replaceFirst(~/^(.+?["'])/, '').replaceFirst(~/(["'].*)$/, '')
+
+}
+
+configurations {
+    kindlegen
+}
+
+dependencies {
+    compile project(':asciidoctor-gradle-jvm')
+    compile project(':kindlegen-gradle')
+
+    intTestOfflineRepo "org.asciidoctor:asciidoctorj:${compileOnlyAsciidoctorJVersion}"
+    intTestOfflineRepo "org.asciidoctor:asciidoctorj-epub3:${downloadOnlyEpubVersion}"
+    intTestOfflineRepo "org.jruby:jruby-complete:${jrubyTestVersion}", {
+        transitive = false
+    }
+    kindlegen project( path : ':kindlegen-gradle', configuration : 'kindlegen')
+}
+
+intTest {
+    ext {
+        findKindleGenDir = { confFiles ->
+            confFiles.find {
+                it.name.toLowerCase().startsWith('kindlegen')
+            }.parentFile.absoluteFile
+        }
+    }
+    systemProperties 'org.asciidoctor.gradle.kindlegen.uri' : "${findKindleGenDir(configurations.kindlegen.files).toURI()}"
+    systemProperties TEST_PROJECTS_DIR : file('src/intTest/projects')
+
+    dependsOn ':kindlegen-gradle:cacheKindleGenBinary'
+}
+
+gradlePlugin {
+    plugins {
+        AsciidoctorEpubPlugin {
+            id = 'org.asciidoctor.org.asciidoctor.jvm.epub'
+            implementationClass = 'org.asciidoctor.gradle.jvm.epub.AsciidoctorJEpubPlugin'
+            description = "Converts Asciidoctor documents to EPUB3/KF8 using AsciidoctorJ${pluginExtraText}"
+        }
+    }
+}

asciidoctor-gradle-jvm-epub/src/intTest/groovy/org/asciidoctor/gradle/jvm/epub/AsciidoctorEpubTaskFunctionalSpec.groovy

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2013-2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.asciidoctor.gradle.jvm.epub
+
+import org.asciidoctor.gradle.jvm.epub.internal.FunctionalSpecification
+import org.gradle.testkit.runner.BuildResult
+import spock.lang.PendingFeature
+import spock.lang.Unroll
+
+@SuppressWarnings(['DuplicateStringLiteral', 'MethodName', 'DuplicateListLiteral'])
+class AsciidoctorEpubTaskFunctionalSpec extends FunctionalSpecification {
+
+    // This line is read by the build script.
+    final static String JRUBY_TEST_VERSION = '9.1.17.0'
+
+    void setup() {
+        createTestProject()
+    }
+
+    @Unroll
+    void 'Run a EPUB generator with format #format (only in JAVA_EXEC mode)'() {
+        given:
+        getBuildFile("""
+
+asciidoctorEpub {
+    sourceDir 'src/docs/asciidoc'
+    ebookFormats ${format}
+    
+    kindlegen {
+        agreeToTermsOfUse = true
+    }
+    
+    asciidoctorj {
+        jrubyVersion = '${JRUBY_TEST_VERSION}'
+    }
+        
+    sources {
+        include 'epub3.adoc'
+    }
+    
+    attributes includedir : {getSourceDir()}
+}
+""")
+        when:
+        BuildResult result = getGradleRunner(['asciidoctorEpub', '-s', '-i']).build()
+
+        then:
+        verifyAll {
+            new File(testProjectDir.root, "build/docs/asciidocEpub/epub3.${ext}").exists()
+            !result.output.contains('include file not found:')
+        }
+
+        where:
+        format  | ext
+        'EPUB3' | 'epub'
+        'KF8'   | 'mobi'
+    }
+
+    @PendingFeature
+    @Unroll
+    void 'Run a EPUB generator with multiple formats in order #formatOrder (only in JAVA_EXEC mode)'() {
+        given:
+        getBuildFile("""
+
+asciidoctorEpub {
+    sourceDir 'src/docs/asciidoc'
+    ebookFormats ${formatOrder}
+    
+    kindlegen {
+        agreeToTermsOfUse = true
+    }
+    
+    asciidoctorj {
+        jrubyVersion = '${JRUBY_TEST_VERSION}'
+    }
+        
+    sources {
+        include 'epub3.adoc'
+    }
+    
+    attributes includedir : {getSourceDir()}
+}
+""")
+        when:
+        BuildResult result = getGradleRunner(['asciidoctorEpub', '-s', '-i']).build()
+
+        then:
+        verifyAll {
+            new File(testProjectDir.root, 'build/docs/asciidocEpub/epub3.mobi').exists()
+            new File(testProjectDir.root, 'build/docs/asciidocEpub/epub3.epub').exists()
+            !result.output.contains('include file not found:')
+        }
+
+        where:
+        formatOrder << ['EPUB3, KF8', 'KF8, EPUB3']
+    }
+
+    File getBuildFile(String extraContent) {
+        File buildFile = testProjectDir.newFile('build.gradle')
+        buildFile << """
+plugins {
+    id 'org.asciidoctor.jvm.epub'
+}
+
+${offlineRepositories}
+
+${extraContent}
+"""
+        buildFile
+    }
+
+}