New generation Asciidoctor Gradle plugins

General: - The version series is 2.0.0. It will be kept as alpha releases for a while. - Project restructured into multiple plugins using '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.2, 4.3.1 & 4.6. (For JDK10 only test against 4.7). - Some integration tests contain JRuby compatibility tests. Current test set is 1.7.27, 9.0.5.0/9.1.0.0, 9.1.17.0, 9.2.0.0. - JDK compatibility testing are done from JDK8 -> JDK10 (Travis) - 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. - Test versions of JRuby and AsciidoctorJ is controlled via test fixtures. - Renamed AsciidoctorPlugin to AsciidoctorCompatiblityPlugin - Provide ability to either use AsciidoctorJ or AsciidoctorJS as the engine. (In this commit only AsciidoctorJ is implemented). - Test result logged in real-time when running on Appveyor. New generation AsciidoctorJ 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`. - AsciidoctorJ v1.6.0-alpha.6 is the default version, but it is possible to set a 1.5.x version if required. - JRuby version can be controlled at both project and task level. If no version is specified at either level, the maximum of default the JRuby version that AsciidoctorJ depends on and a coded minimum safe version of JRuby, will be used. - AsciidoctorJExtension maintains it's own detached configuration which can be fine turned via resolution strategies for edge cases. - the `org.asciidoctor.jvm.base` plugin adds a dependency report specifically for the detached configuration. - GroovyDSL extensions are now registered either 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. - If the PDF backend is used and the JRuby version starts with '9.x' then place SnakeYaml v1.13 on the classpath. - 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`. Also depend on `groovy-all` dependency rather than `localGroovy()` to see if that provides relief for the issue. - Asciidoctorj-diagram supprot is in-built. Just specify the version on the extension and the artifact will be added to the classpatj. The necessary addition will be made to `requires` as well. - 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) - Various tests use a combination of JRuby & AsciidoctorJ versions to test compatibility at the integration test level. Known issues: - Intermittent failures 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. - KF8 conversions fails under Windows. Related to asciidoctor/asciidoctorj#659 & jruby/jruby#4943. - Does not work with JDK9 (but does with JDK10). 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. - asciidoctor#238 has been forard-ported to check that the same issue do not occur when using the compatibility task.
ysb33r · Jun 27, 2018 · 92f44f2 · 92f44f2
1 parent 6010ecd
commit 92f44f2
Show file tree

Hide file tree

Showing 125 changed files with 8,055 additions and 1,880 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -4,18 +4,21 @@ install: true
 
 cache:
     directories:
-        - $HOME/.m2
         - $HOME/.gradle
+        - .gradle/
+        - testfixtures/offline-repo/build/root
 
 before_script:
     - ./gradlew --version
 
 script:
-    - TERM=dumb ./gradlew build jacocoTestReport
+    - ./gradlew --console=plain --warning-mode=all build jacocoTestReport
 
 jdk:
-    - oraclejdk8
-    - oraclejdk9
+    - openjdk8
+    - oraclejdk10
+#    - openjdk9
+#    - oraclejdk9
 
 after_success:
     - ./gradlew coveralls
diff --git a/README.adoc b/README.adoc
diff --git a/appveyor.yml b/appveyor.yml
@@ -13,11 +13,15 @@ install:
   - echo %PATH%
   - gradlew.bat --version
 build_script:
-  - gradlew.bat -u -i clean assemble
+  - gradlew.bat --console=plain --warning-mode=all -s clean assemble
 test_script:
-  - gradlew.bat -u -i -S check
+  - gradlew.bat --console=plain --warning-mode=all -s check --no-parallel
+after_test:
+  - gradlew.bat --stop
 cache:
   - .gradle
   - C:\Users\appveyor\.gradle
+  - testfixtures\offline-repo\build\root
+
 on_failure:
   - echo Somebody setup us the bomb
diff --git a/asciidoctor-gradle-base/build.gradle b/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'
+        }
+    }
+}
diff --git a/...ctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/AsciidoctorBasePlugin.groovy b/...ctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/AsciidoctorBasePlugin.groovy
@@ -0,0 +1,34 @@
+/*
+ * 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 2.0.0
+ * @author Schalk W. Cronjé
+ */
+@CompileStatic
+class AsciidoctorBasePlugin implements Plugin<Project> {
+
+    void apply(Project project) {
+        project.with {
+            apply plugin : 'base'
+        }
+    }
+}
diff --git a/asciidoctor-gradle-base/src/main/groovy/org/asciidoctor/gradle/base/SafeMode.groovy b/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
+        }
+    }
+
+}
diff --git a/...or-gradle-base/src/main/resources/META-INF/gradle-plugins/org.asciidoctor.base.properties b/...or-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
diff --git a/asciidoctor-gradle-jvm-epub/build.gradle b/asciidoctor-gradle-jvm-epub/build.gradle
@@ -0,0 +1,23 @@
+
+dependencies {
+    compile project(':asciidoctor-gradle-jvm')
+    compile project(':kindlegen-gradle')
+
+    intTestOfflineRepo "org.asciidoctor:asciidoctorj:${compileOnlyAsciidoctorJVersion}"
+    intTestOfflineRepo "org.asciidoctor:asciidoctorj-epub3:${downloadOnlyEpubVersion}"
+}
+
+intTest {
+    systemProperties 'org.asciidoctor.gradle.kindlegen.uri' : offlineRepoBinariesRoot.toURI()
+    systemProperties TEST_PROJECTS_DIR : file('src/intTest/projects')
+}
+
+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}"
+        }
+    }
+}
diff --git a/...c/intTest/groovy/org/asciidoctor/gradle/jvm/epub/AsciidoctorEpubTaskFunctionalSpec.groovy b/...c/intTest/groovy/org/asciidoctor/gradle/jvm/epub/AsciidoctorEpubTaskFunctionalSpec.groovy
@@ -0,0 +1,159 @@
+/*
+ * 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.asciidoctor.gradle.testfixtures.jvm.JRubyTestVersions
+import org.gradle.testkit.runner.BuildResult
+import spock.lang.IgnoreIf
+import spock.lang.Issue
+import spock.lang.PendingFeature
+import spock.lang.Unroll
+
+@SuppressWarnings(['DuplicateStringLiteral', 'MethodName', 'DuplicateListLiteral'])
+class AsciidoctorEpubTaskFunctionalSpec extends FunctionalSpecification {
+
+    final static String JRUBY_TEST_VERSION = JRubyTestVersions.AJ15_SAFE_MAXIMUM
+
+    void setup() {
+        createTestProject()
+    }
+
+    void 'Run a EPUB generator with format EPUB3 (only in JAVA_EXEC mode)'() {
+        given:
+        getSingleFormatBuildFile('EPUB3')
+
+        when:
+        BuildResult result = getGradleRunner(['asciidoctorEpub', '-s', '-i']).build()
+
+        then:
+        verifyAll {
+            new File(testProjectDir.root, 'build/docs/asciidocEpub/epub3.epub').exists()
+            !result.output.contains('include file not found:')
+        }
+    }
+
+    @IgnoreIf({FunctionalSpecification.OS.windows})
+    void 'Non-Windows: Run a EPUB generator with format KF8 (only in JAVA_EXEC mode on)'() {
+        given:
+        getSingleFormatBuildFile('KF8')
+
+        when:
+        BuildResult result = getGradleRunner(['asciidoctorEpub', '-s', '-i']).build()
+
+        then:
+        verifyAll {
+            new File(testProjectDir.root, 'build/docs/asciidocEpub/epub3.mobi').exists()
+            !result.output.contains('include file not found:')
+        }
+    }
+
+    @Issue('https://github.com/asciidoctor/asciidoctorj/issues/659')
+    @IgnoreIf({!FunctionalSpecification.OS.windows})
+    @PendingFeature
+    void 'Windows: Run a EPUB generator with format KF8 (only in JAVA_EXEC mode on)'() {
+        given:
+        getSingleFormatBuildFile('KF8')
+
+        when:
+        BuildResult result = getGradleRunner(['asciidoctorEpub', '-s', '-i']).build()
+
+        then:
+        verifyAll {
+            new File(testProjectDir.root, 'build/docs/asciidocEpub/epub3.mobi').exists()
+            !result.output.contains('include file not found:')
+        }
+    }
+
+    @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 getSingleFormatBuildFile(final String format) {
+        getBuildFile( """
+
+asciidoctorEpub {
+    sourceDir 'src/docs/asciidoc'
+    ebookFormats ${format}
+    
+    kindlegen {
+        agreeToTermsOfUse = true
+    }
+    
+    asciidoctorj {
+        jrubyVersion = '${JRUBY_TEST_VERSION}'
+    }
+        
+    sources {
+        include 'epub3.adoc'
+    }
+    
+    attributes includedir : {getSourceDir()}
+}
+"""
+        )
+    }
+
+    File getBuildFile(String extraContent) {
+        File buildFile = testProjectDir.newFile('build.gradle')
+        buildFile << """
+plugins {
+    id 'org.asciidoctor.jvm.epub'
+}
+
+${offlineRepositories}
+
+${extraContent}
+"""
+        buildFile
+    }
+
+}