From 9d7f61975163231e43934ee3b6a157cb8688c8ef Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Sun, 10 Mar 2024 22:40:23 +0100 Subject: [PATCH] Build antora docs (main branch) (#722) * Moved docs to an Antora structure under '/docs' * Created antora.yaml * Added nav.adoc respecting current structure. * Created modules 'ROOT' and 'apendices' * Moved source files to respective modules * Updated section level (reduced in 1) * Created soft link to include content from project sources * Cleaned README.adoc * Removed un-used attributes * Updated content * Removed now unnecessary elements: * Gradle docs modules * 'push-documentation' GH Action * Fixes: * Fixed invalid references (I am not upgrading all references from [legacy to modern](https://docs.asciidoctor.org/asciidoc/latest/sections/custom-ids/) in this PR) * Several typos & formatting Outside of the PR I renamed development-v3.x branch to maintenance-3.x, to align with the documentation done prior to my changes. --- .github/workflows/build.yaml | 11 +- .github/workflows/push-documentation.yml | 34 ---- README.adoc | 26 +-- ...stractImplementationEngineExtension.groovy | 3 +- docs/README-IntelliJ.adoc | 10 -- docs/antora.yml | 34 ++++ docs/antora/build.gradle | 45 ------ docs/build.gradle | 148 ------------------ docs/gh-pages/build.gradle | 35 ----- docs/gradle.properties | 1 - docs/gradle/load-properties.gradle | 13 -- docs/gradle/wrapper | 1 - docs/gradlew | 2 - docs/gradlew.bat | 8 - docs/modules/ROOT/examples/base | 1 + docs/modules/ROOT/examples/jvm | 1 + docs/modules/ROOT/nav.adoc | 18 +++ .../ROOT/pages}/asciidoctor-diagram.adoc | 5 +- .../asciidoctoreditorconfig-plugin.adoc | 13 +- .../ROOT/pages}/asciidoctorj-base-plugin.adoc | 39 +++-- .../asciidoctorj-compatiblity-plugin.adoc | 9 +- .../asciidoctorj-custom-extensions.adoc | 14 +- .../ROOT/pages}/asciidoctorj-epub-plugin.adoc | 9 +- .../ROOT/pages}/asciidoctorj-gems-plugin.adoc | 7 +- .../pages/asciidoctorj-leanpub-plugin.adoc | 9 ++ .../ROOT/pages}/asciidoctorj-pdf-plugin.adoc | 14 +- .../ROOT/pages}/asciidoctorj-plugin.adoc | 12 +- .../pages}/asciidoctorj-revealjs-plugin.adoc | 15 +- .../ROOT/pages}/asciidoctorjs-plugin.adoc | 9 +- .../pages}/common-task-configuration.adoc | 48 +++--- .../ROOT/pages}/compatibility.adoc | 2 +- .../parts => modules/ROOT/pages}/docinfo.adoc | 6 +- .../ROOT/pages}/exporting-slides.adoc | 16 +- docs/modules/ROOT/pages/index.adoc | 10 ++ .../ROOT/pages}/kindlegen-plugin.adoc | 6 +- .../ROOT/pages}/quick-start.adoc | 6 +- .../ROOT/pages}/upgrading.adoc | 17 +- docs/modules/appendices/nav.adoc | 4 + docs/modules/appendices/pages/hacking.adoc | 10 ++ .../appendices/pages}/known-limitations.adoc | 3 +- .../appendices/pages}/tips-and-tricks.adoc | 14 +- docs/modules/file.adoc | 1 + docs/publish-docs-from-travis | 15 -- docs/settings.gradle | 6 - docs/src/docs/asciidoc/appendix/hacking.adoc | 4 - docs/src/docs/asciidoc/attributes.adoc | 25 --- docs/src/docs/asciidoc/index.adoc | 54 ------- .../parts/asciidoctorj-leanpub-plugin.adoc | 9 -- .../gradle/jvm/AsciidoctorJExtension.groovy | 3 +- 49 files changed, 238 insertions(+), 567 deletions(-) delete mode 100644 .github/workflows/push-documentation.yml delete mode 100644 docs/README-IntelliJ.adoc create mode 100644 docs/antora.yml delete mode 100644 docs/antora/build.gradle delete mode 100644 docs/build.gradle delete mode 100644 docs/gh-pages/build.gradle delete mode 100644 docs/gradle.properties delete mode 100644 docs/gradle/load-properties.gradle delete mode 120000 docs/gradle/wrapper delete mode 100755 docs/gradlew delete mode 100644 docs/gradlew.bat create mode 120000 docs/modules/ROOT/examples/base create mode 120000 docs/modules/ROOT/examples/jvm create mode 100644 docs/modules/ROOT/nav.adoc rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctor-diagram.adoc (92%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctoreditorconfig-plugin.adoc (82%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-base-plugin.adoc (69%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-compatiblity-plugin.adoc (90%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-custom-extensions.adoc (93%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-epub-plugin.adoc (80%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-gems-plugin.adoc (77%) create mode 100644 docs/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-pdf-plugin.adoc (88%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-plugin.adoc (61%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorj-revealjs-plugin.adoc (90%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/asciidoctorjs-plugin.adoc (58%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/common-task-configuration.adoc (86%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/compatibility.adoc (92%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/docinfo.adoc (79%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/exporting-slides.adoc (73%) create mode 100644 docs/modules/ROOT/pages/index.adoc rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/kindlegen-plugin.adoc (85%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/quick-start.adoc (64%) rename docs/{src/docs/asciidoc/parts => modules/ROOT/pages}/upgrading.adoc (93%) create mode 100644 docs/modules/appendices/nav.adoc create mode 100644 docs/modules/appendices/pages/hacking.adoc rename docs/{src/docs/asciidoc/appendix => modules/appendices/pages}/known-limitations.adoc (95%) rename docs/{src/docs/asciidoc/appendix => modules/appendices/pages}/tips-and-tricks.adoc (86%) create mode 100644 docs/modules/file.adoc delete mode 100755 docs/publish-docs-from-travis delete mode 100644 docs/settings.gradle delete mode 100644 docs/src/docs/asciidoc/appendix/hacking.adoc delete mode 100644 docs/src/docs/asciidoc/attributes.adoc delete mode 100644 docs/src/docs/asciidoc/index.adoc delete mode 100644 docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index e886629f1..24acffdf5 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -1,5 +1,14 @@ name: Build -on: [push, pull_request] +on: + push: + paths-ignore: + - '*.adoc' + - docs/** + pull_request: + paths-ignore: + - '*.adoc' + - docs/** + jobs: check: runs-on: ubuntu-latest diff --git a/.github/workflows/push-documentation.yml b/.github/workflows/push-documentation.yml deleted file mode 100644 index 62907150a..000000000 --- a/.github/workflows/push-documentation.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: Push documentation -on: - push: - branches: - - master - - development-4.x -permissions: - contents: write -jobs: - push-docs: - runs-on: ubuntu-latest - if: github.repository == 'asciidoctor/asciidoctor-gradle-plugin' - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-java@v4 - with: - java-version: 11 - distribution: temurin - - uses: gradle/actions/setup-gradle@v3 - with: - gradle-home-cache-cleanup: true - - name: Combine documentation - run: | - cd docs - ./gradlew --console=plain -q combineDocs - - name: Publish documentation - env: - CI_BRANCH: ${{ github.ref_name }} - REPO_URL: ${{ github.server_url }}/${{ github.repository }} - GRGIT_USER: 'GH Action User' - GRGIT_PASS: ${{ secrets.GITHUB_TOKEN }} - run: | - cd docs - ./gradlew --console=plain :gh-pages:publishDocs --info --stacktrace diff --git a/README.adoc b/README.adoc index 4810eb9de..828a328c6 100644 --- a/README.adoc +++ b/README.adoc @@ -1,24 +1,9 @@ = Asciidoctor Gradle Plugin Andres Almiray -:version: 4.0.0 -:version-published: 4.0.0-alpha.1 -:asciidoc-url: http://asciidoc.org -:asciidoctor-url: http://asciidoctor.org -:issues: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues +:asciidoc-url: https://asciidoc.org +:asciidoctor-url: https://asciidoctor.org :gradle-url: http://gradle.org/ -:asciidoctor-maven-plugin: https://github.com/asciidoctor/asciidoctor-maven-plugin -:kotlindsl: https://github.com/gradle/kotlin-dsl[Gradle Kotlin DSL] -:lightguard: https://github.com/LightGuard -:asciidoctorj: https://github.com/asciidoctor/asciidoctorj -:asciidoctorj-name: AsciidoctorJ -:asciidoctorjs-name: Asciidoctor.js -:asciidoctorj-epub-name: Asciidoctorj-EPUB -:asciidoctorj-pdf-name: Asciidoctorj-PDF -:lordofthejars: https://github.com/lordofthejars -:asciidoctor-docs: http://asciidoctor.org/docs/ :asciidoctor-development-docs: https://asciidoctor.github.io/asciidoctor-gradle-plugin/ -:plugin-name: Asciidoctor Gradle plugin -:project-name: asciidoctor-gradle-plugin :project-full-path: asciidoctor/asciidoctor-gradle-plugin :github-branch: master :linkattrs: @@ -36,9 +21,9 @@ ifdef::env-github[] endif::[] ifdef::status[] -image:https://github.com/asciidoctor/asciidoctor-gradle-plugin/workflows/Build/badge.svg[GitHub Actions Status, link=https://github.com/asciidoctor/asciidoctor-gradle-plugin/actions] -image:http://img.shields.io/coveralls/{project-full-path}/{github-branch}.svg[Coverage Status, link=https://coveralls.io/r/{project-full-path}] -image:http://img.shields.io/badge/license-ASF2-blue.svg[Apache License 2, link=http://www.apache.org/licenses/LICENSE-2.0.txt] +image:https://github.com/asciidoctor/asciidoctor-gradle-plugin/workflows/Build/badge.svg[GitHub Actions Status,link=https://github.com/asciidoctor/asciidoctor-gradle-plugin/actions] +image:http://img.shields.io/coveralls/{project-full-path}/{github-branch}.svg[Coverage Status,link=https://coveralls.io/r/{project-full-path}] +image:http://img.shields.io/badge/license-ASF2-blue.svg[Apache License 2,link=http://www.apache.org/licenses/LICENSE-2.0.txt] image:https://gitlab.com/asciidoctor/asciidoctor-gradle-plugin/badges/master/pipeline.svg[link="https://gitlab.com/asciidoctor/asciidoctor-gradle-plugin/commits/master",title="pipeline status"] endif::[] @@ -54,4 +39,3 @@ PRs are preferably taking against this branch. The 3.x series of the plugin is now in maintenance only mode. PRs for that should be raised against the link:https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-3.x[maintenance-3.x]branches. endif::[] - diff --git a/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy b/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy index 7c53cfe94..d21e296b0 100644 --- a/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy +++ b/base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy @@ -52,7 +52,8 @@ class AbstractImplementationEngineExtension tag::extension-property[] attributes:: Asciidoctor attributes. Use `attributes` to append and `setAttributes` to replace any current attributes with a new set. - Attribute values are lazy-evaluated to strings. See <> for more detail. + Attribute values are lazy-evaluated to strings. + See <> for more detail. end::extension-property[] ------------------------- */ diff --git a/docs/README-IntelliJ.adoc b/docs/README-IntelliJ.adoc deleted file mode 100644 index 7c637c035..000000000 --- a/docs/README-IntelliJ.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= IntelliJ support - -In order to edit the documents in IntelliJ add the `docs folder as a new module in IntelliJ. Check the `auto-import` box and use the `Gradle Wrapper` option. - -In order to have the correct attributes made available to the Asciidoctor preview in IntelliJ, do - -[listing.terminal] ----- -$ cd docs && ./gradlew asciidoctorEditorConfig ----- \ No newline at end of file diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 000000000..9da788455 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,34 @@ +name: gradle-plugin +title: Gradle Plugin Suite +version: '4.0' +asciidoc: + attributes: + release-version: 4.0.2 + project-full-path: asciidoctor/asciidoctor-gradle-plugin + project-name: asciidoctor-gradle-plugin + project-repo-url: https://github.com/asciidoctor/asciidoctor-gradle-plugin + plugin-name: Asciidoctor Gradle plugin + asciidoc-url: https://asciidoc.org + asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest + asciidoctor-docs: https://docs.asciidoctor.org/asciidoctor/latest + asciidoctor-maven-plugin-name: Asciidoctor Maven Plugin + asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin + asciidoctor-url: https://asciidoctor.org + asciidoctorj-epub-name: Asciidoctorj EPUB3 + asciidoctorj-epub-url: https://github.com/asciidoctor/asciidoctorj-epub3 + asciidoctorj-name: AsciidoctorJ + asciidoctorj-pdf-name: Asciidoctorj PDF + asciidoctorj-pdf-url: https://github.com/asciidoctor/asciidoctorj-pdf + asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj + asciidoctorjs-name: Asciidoctor.js + asciidoctorjs-url: https://github.com/asciidoctor/asciidoctor.js + gradle-url: https://gradle.org/ + issues-asciidoctorj: https://github.com/asciidoctor/asciidoctorj/issues/ + issues-jruby: https://github.com/asciidoctor/asciidoctorj/issues/ + jruby-name: JRuby + kotlindsl: https://github.com/gradle/kotlin-dsl[Gradle Kotlin DSL] + lightguard: https://github.com/LightGuard[Jason Porter] + lordofthejars: https://github.com/lordofthejars[Alex Soto] +nav: + - modules/ROOT/nav.adoc + - modules/appendices/nav.adoc diff --git a/docs/antora/build.gradle b/docs/antora/build.gradle deleted file mode 100644 index 738def79d..000000000 --- a/docs/antora/build.gradle +++ /dev/null @@ -1,45 +0,0 @@ -plugins { - id 'org.ajoberstar.git-publish' -} - -ext { - currentBranch = System.getenv('CI_BRANCH') ?: 'not-on-ci' - pushDocs = currentBranch.matches(~/^master|development-.+|maintenance-.+$/) -} - -gitPublish { - repoUri = gitHubRepoUri - branch = antoraBranch - - contents { - into version - from rootProject.tasks.prepareSources, { - into 'sources' - } - from "${rootDir}/src/docs", { - include 'asciidoc/**' - } - - // TODO: Wait for Antora to support Javadoc - // See https://gitlab.com/antora/antora/issues/439 -// from rootProject.tasks.combinedDocs, { -// exclude 'user-guide' -// } - } - - preserve { - include '**' - exclude "${version}/**" - } - - commitMessage = "Updating ${version} sources for Antora" -} - -task publishDocs { - if (pushDocs) { - dependsOn gitPublishPush - } - doFirst { - logger.lifecycle "${currentBranch} is ${pushDocs ? 'a match. Push attempted' : 'not a match. Push skipped.'}" - } -} diff --git a/docs/build.gradle b/docs/build.gradle deleted file mode 100644 index 2cd20f5f6..000000000 --- a/docs/build.gradle +++ /dev/null @@ -1,148 +0,0 @@ -plugins { - id 'idea' - id 'org.asciidoctor.jvm.convert' apply false - id 'org.asciidoctor.editorconfig' apply false - id 'org.ajoberstar.git-publish' version '4.2.2' apply false -} - -repositories { - mavenCentral() -} - -ext { - asciidoctorSourceSyncDir = file("${buildDir}/docs/sources") - asciidoctorCombinedDocsDir = file("${buildDir}/docs/combined") - - docProjects = [ - new IncludedProject(name: 'asciidoctoreditorconfig', dir: 'asciidoctoreditorconfig'), - new IncludedProject(name: 'asciidoctor-gradle-base', dir: 'base'), - new IncludedProject(name: 'asciidoctor-gradle-jvm-gems', dir: 'gems'), - new IncludedProject(name: 'asciidoctor-gradle-js', dir: 'js'), - new IncludedProject(name: 'asciidoctor-gradle-jvm', dir: 'jvm'), - new IncludedProject(name: 'asciidoctor-gradle-jvm-epub', dir: 'jvm-epub'), - new IncludedProject(name: 'asciidoctor-gradle-jvm-pdf', dir: 'jvm-pdf'), - ] -} - -allprojects { - apply from: "${rootDir}/gradle/load-properties.gradle" - version = pluginsGradleProperties.version -} - -apply plugin: 'org.asciidoctor.jvm.convert' -apply plugin: 'org.asciidoctor.editorconfig' - -configurations { - asciidocExtensions -} - -dependencies { -// asciidocExtensions 'com.bmuschko:asciidoctorj-tabbed-code-extension:0.1' -} - -task prepareSources(type: Sync) { - group 'documentation' - description 'Copy sources from all plugin projects' - into asciidoctorSourceSyncDir - - docProjects.each { proj -> - from pluginProjectDir(proj), { - into proj.dir - include 'src/**' - exclude '**/META-INF/**' - } - } -} - -asciidoctorj { - fatalWarnings missingIncludes() -} - -asciidoctor { - group 'documentation' - description 'Build HTML documentation' - - dependsOn prepareSources - baseDirFollowsSourceDir() - // configurations 'asciidocExtensions' - sourceDir 'src/docs/asciidoc' - sources { include 'index.adoc' } - attributes toc: 'right', - toclevels: 2, - 'source-highlighter': 'rouge' - - docProjects.each { proj -> - attributes "plugin-${proj.dir}": file("${prepareSources.destinationDir}/${proj.dir}/src") - } -} - -task generateIndex { - group 'documentation' - description 'Generate index source file' - ext { - outputFile = file("${buildDir}/docs/index-source/index.adoc") - } - - inputs.property 'docProjects', docProjects - outputs.file outputFile - - doLast { - outputFile.parentFile.mkdirs() - outputFile.withWriter { w -> - w.println "= Asciidoctor Gradle Plugin Suite v${version}" - w.println '' - w.println "* link:./user-guide/[User guide]" - - docProjects*.dir.sort().each { projDir -> - w.println "* link:./api-${projDir}/[API: ${projDir}]" - } - } - } -} - -task asciidocIndex(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) { - group 'documentation' - description 'Generate HTML index' - - dependsOn generateIndex - sourceDir generateIndex.outputFile.parentFile - outputDir "${buildDir}/docs/index" -} - -task combineDocs(type: Sync) { - group 'documentation' - description 'Combine all generated documentation into a single tree' - - dependsOn docProjects.collect { includedBuildTask(it, 'groovydoc') } - into asciidoctorCombinedDocsDir - from asciidocIndex - from asciidoctor, { - into 'user-guide' - } - - docProjects.each { proj -> - from "${pluginProjectDir(proj)}/build/docs/groovydoc", { - into "api-${proj.dir}" - } - } -} - -asciidoctorEditorConfig { - attributes revnumber: project.version - additionalAttributes 'src/docs/asciidoc/attributes.adoc' - additionalAttributes asciidoctor.asciidoctorj - dependsOn prepareSources -} - -class IncludedProject implements Serializable { - String name - String dir -} - -File pluginProjectDir(IncludedProject pluginName) { - new File(rootProject.projectDir.parentFile, pluginName.dir) -} - -TaskReference includedBuildTask(IncludedProject proj, String task) { - gradle.includedBuild('asciidoctor-gradle-plugin').task(":${proj.name}:${task}") -} diff --git a/docs/gh-pages/build.gradle b/docs/gh-pages/build.gradle deleted file mode 100644 index 719bcaa78..000000000 --- a/docs/gh-pages/build.gradle +++ /dev/null @@ -1,35 +0,0 @@ -plugins { - id 'base' - id 'org.ajoberstar.git-publish' -} - -ext { - currentBranch = System.getenv('CI_BRANCH') ?: 'not-on-ci' - pushDocs = currentBranch.matches(~/^master|development-.+|maintenance-.+$/) -} - -gitPublish { - repoUri = System.getenv('REPO_URL') ?: gitHubRepoUri - branch = 'gh-pages' - - contents { - into currentBranch - from rootProject.tasks.combineDocs - } - - preserve { - include '**' - exclude "${currentBranch}/**" - } - - commitMessage = "Updating SNAPSHOT documentation for ${currentBranch} at ${version}" -} - -task publishDocs { - if (pushDocs) { - dependsOn gitPublishPush - } - doFirst { - logger.lifecycle "${currentBranch} is ${pushDocs ? 'a match. Push attempted' : 'not a match. Push skipped.'}" - } -} diff --git a/docs/gradle.properties b/docs/gradle.properties deleted file mode 100644 index c2f4a03fb..000000000 --- a/docs/gradle.properties +++ /dev/null @@ -1 +0,0 @@ -gitHubRepoUri=https://github.com/asciidoctor/asciidoctor-gradle-plugin.git diff --git a/docs/gradle/load-properties.gradle b/docs/gradle/load-properties.gradle deleted file mode 100644 index 20169fbbb..000000000 --- a/docs/gradle/load-properties.gradle +++ /dev/null @@ -1,13 +0,0 @@ -class LoadProperties { - static Properties get(File path) { - def props = new Properties() - path.withInputStream { strm -> - props.load(strm) - } - props - } -} - -ext { - pluginsGradleProperties = LoadProperties.get(file("${rootDir}/../gradle.properties")) -} \ No newline at end of file diff --git a/docs/gradle/wrapper b/docs/gradle/wrapper deleted file mode 120000 index cbfd2e1d3..000000000 --- a/docs/gradle/wrapper +++ /dev/null @@ -1 +0,0 @@ -../../gradle/wrapper/ \ No newline at end of file diff --git a/docs/gradlew b/docs/gradlew deleted file mode 100755 index 7bd0f031c..000000000 --- a/docs/gradlew +++ /dev/null @@ -1,2 +0,0 @@ -#!/usr/bin/env bash -exec $(dirname $0)/../gradlew $@ \ No newline at end of file diff --git a/docs/gradlew.bat b/docs/gradlew.bat deleted file mode 100644 index be82f97e0..000000000 --- a/docs/gradlew.bat +++ /dev/null @@ -1,8 +0,0 @@ -@rem -@rem Credits to Jez Higgins (@jezhiggins) & Ralph McArdell (@ralph-mcardell) -@rem for hints on how to have a very simplified batch file. -@rem -@echo off - -setlocal enableextensions -%~p0\..\gradlew.bat %* \ No newline at end of file diff --git a/docs/modules/ROOT/examples/base b/docs/modules/ROOT/examples/base new file mode 120000 index 000000000..393ad7fc9 --- /dev/null +++ b/docs/modules/ROOT/examples/base @@ -0,0 +1 @@ +../../../../base \ No newline at end of file diff --git a/docs/modules/ROOT/examples/jvm b/docs/modules/ROOT/examples/jvm new file mode 120000 index 000000000..401facfb7 --- /dev/null +++ b/docs/modules/ROOT/examples/jvm @@ -0,0 +1 @@ +../../../../jvm \ No newline at end of file diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 000000000..c39e8c4aa --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,18 @@ +* xref:index.adoc[] +* xref:compatibility.adoc[] +* xref:quick-start.adoc[] +* xref:common-task-configuration.adoc[] +* xref:asciidoctorj-base-plugin.adoc[] +* xref:asciidoctorj-plugin.adoc[] +* xref:asciidoctorj-pdf-plugin.adoc[] +* xref:asciidoctorj-epub-plugin.adoc[] +* xref:asciidoctorj-revealjs-plugin.adoc[] +// * xref:asciidoctorj-leanpub-plugin.adoc[] +* xref:asciidoctorj-gems-plugin.adoc[] +* xref:asciidoctor-diagram.adoc[] +// * xref:kindlegen-plugin.adoc[] +* xref:asciidoctorj-custom-extensions.adoc[] +* xref:asciidoctorjs-plugin.adoc[] +* xref:asciidoctoreditorconfig-plugin.adoc[] +* xref:docinfo.adoc[] +* xref:upgrading.adoc[] diff --git a/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc b/docs/modules/ROOT/pages/asciidoctor-diagram.adoc similarity index 92% rename from docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc rename to docs/modules/ROOT/pages/asciidoctor-diagram.adoc index c697ca49a..73dfb8229 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctor-diagram.adoc +++ b/docs/modules/ROOT/pages/asciidoctor-diagram.adoc @@ -1,5 +1,4 @@ -[[diagram]] -== Using AsciidoctorJ Diagram += Using AsciidoctorJ Diagram The new plugins have built-in support for `asciidoctorj-diagram`. Simply add the following to the project or task extension and diagramming will be available. If it is not set the `asciidoctorj-diagram` JAR will not be added to the classpath. @@ -18,7 +17,7 @@ asciidoctorj { With this enhancement, there is also no longer a need to add `requires 'asciidoctor-diagram'`. -NOTE: If you using OpenJDK 9/10 on MacOS you might find an error such as below +NOTE: If you are using OpenJDK 9/10 on macOS you might find an error such as below ---- Caused by: java.lang.UnsatisfiedLinkError: /path/to/openjdk10/lib/libfontmanager.dylib: dlopen(/path/to/openjdk10/lib/libfontmanager.dylib, 1): Library not loaded: /Users/jenkins/workspace/openjdk10_build_x86-64_macos/openjdk/installedfreetype/lib/libfreetype.6.dylib diff --git a/docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc b/docs/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc similarity index 82% rename from docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc index 11bdc6be1..50361060a 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctoreditorconfig-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctoreditorconfig-plugin.adoc @@ -1,11 +1,11 @@ -== The Asciidoctor Editor Config Plugin += The Asciidoctor Editor Config Plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.editorconfig' version '{revnumber}' + id 'org.asciidoctor.editorconfig' version '{release-version}' } ---- @@ -14,13 +14,13 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.editorconfig") version "{revnumber}" + id("org.asciidoctor.editorconfig") version "{release-version}" } ---- Writes an `.asciidoctorconfig` file so that supporting IDEs can render Asciidoctor-based documentation correctly. -=== Adding attributes +== Adding attributes [source,groovy,role="primary"] ---- @@ -36,12 +36,11 @@ asciidoctorEditorConfig { <2> Adds all attributes defined on the project extension to the generated file. These attributes are added after the predefined attributes. <3> Appends the context of the specified file to the generated file. Context such as this is added last. This method also allows you to define a number of attributes in your source directory and include them in your main Asciidoc file as well as send them to `.asciidoctorconfig`. - -=== Changing the output directory +== Changing the output directory [source,groovy,role="primary"] ---- asciidoctorEditorConfig { destinationDir = 'docs' } ----- \ No newline at end of file +---- diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-base-plugin.adoc similarity index 69% rename from docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-base-plugin.adoc index 42771549c..770c83554 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-base-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-base-plugin.adoc @@ -1,4 +1,4 @@ -== AsciidoctorJ Base Plugin += AsciidoctorJ Base Plugin This plugin is automatically applied by all AsciidoctorJ-based plugins. @@ -40,17 +40,16 @@ asciidoctor { The {asciidoctorj-name}-specific entities that can be set are: [horizontal] -include::{plugin-jvm}/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy[indent=0,tags="extension-property"] +include::ROOT:example$jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy[indent=0,tags="extension-property"] The following common entities can also be set: [horizontal] -include::{plugin-base}/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy[indent=0,tags="extension-property"] +include::ROOT:example$base/src/main/groovy/org/asciidoctor/gradle/base/AbstractImplementationEngineExtension.groovy[indent=0,tags="extension-property"] // TODO: Split attributes into a standalone section that is not part of base plugin. -[[attributes,Setting Attributes]] -[[options,Setting Options]] -=== Options & Attributes +[#options-and-attributes] +== Options & Attributes The following options may be set using the extension's `options` property @@ -108,13 +107,12 @@ These attributes may be overridden by explicit user input. Refer to the {asciidoctor-docs}[Asciidoctor documentation] to learn more about these options and attributes. -Attribute values defined on the build file will win over values defined on the documents themselves. You can change -this behavior by appending an `@` at the end of the value when defined in the build file. Please refer to -link:{asciidoctor-userguide}#attribute-assignment-precedence[Attribute assignment precedence, window="_blank"] -for more information. +Attribute values defined on the build file will win over values defined on the documents themselves. +You can change this behavior by appending an `@` at the end of the value when defined in the build file. +Please refer to link:{asciidoc-docs}/attributes/assignment-precedence#altering-the-assignment-precedence[Attribute assignment precedence, window="_blank"] for more information. [[asciidoctorj-modules,{asciidoctorj-name} Modules]] -=== Versions of modules +== Versions of modules The modules block currently supports four elements @@ -141,13 +139,14 @@ asciidoctorj { } } ---- -<1> {asciidoctorj-epub-name} version. If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend and not using the EPUB plugin, then you need to set a version here. -<2> {asciidoctorj-pdf-name} version. If not specified asciidoctorj-pdf will not be on the classpath. If you plan to use the PDF backend and not using the PDF plugin, then you need to set a version here. -<3> See <>, -<4> Version of Groovy Extensions DSL. If not specified and no extensions are specified, Groovy DSL will not be used. However, if any extensions are added without setting an explicit version and default version will be used. -<5> {asciidoctorj-leanpub-name} version. If not specified asciidoctorj-leanpub will not be on the classpath. If you plan to use the Leanpub backend and not using the Leanpub plugin, then you need to set a version here. +<1> {asciidoctorj-pdf-url}[{asciidoctorj-pdf-name}] version. If not specified asciidoctorj-pdf will not be on the classpath. If you plan to use the PDF backend and not using the PDF plugin, then you need to set a version here. +<2> {asciidoctorj-epub-url}[{asciidoctorj-epub-name}] version. If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend and not using the EPUB plugin, then you need to set a version here. +<3> See xref:page$asciidoctor-diagram.adoc[]. +<4> Version of https://github.com/asciidoctor/asciidoctorj-groovy-dsl[Groovy Extensions DSL]. If not specified and no extensions are specified, Groovy DSL will not be used. However, if any extensions are added without setting an explicit version and default version will be used. +<5> https://github.com/asciidoctor/asciidoctor-leanpub-converter[Asciidoctor Leanpub Converter] version. If not specified asciidoctorj-leanpub will not be on the classpath. If you plan to use the Leanpub backend and not using the Leanpub plugin, then you need to set a version here. -When using the {kotlin-dsl} the same settings can be achieved use something similar `getModules().getPdf().version("1.2.3")`. In a similar fashion shortcuts can be achieved in the {groovy-dsl}: +When using the Kotlin DSL the same settings can be achieved use something similar `getModules().getPdf().version("1.2.3")`. +In a similar fashion shortcuts can be achieved in the Groovy DSL: [source,groovy,role="primary"] .build.gradle @@ -172,7 +171,7 @@ asciidoctorj { <1> Set the {asciidoctorj-pdf-name} version to `1.2.3`. <2> Use the default version of {asciidoctorj-pdf-name}. -=== Applying the {asciidoctorj-name} Base plugin on its own +== Applying the {asciidoctorj-name} Base plugin on its own If none of the default conventions work for you, the base plugin can be applied on its own. @@ -181,7 +180,7 @@ If none of the default conventions work for you, the base plugin can be applied .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.base' version '{revnumber}' + id 'org.asciidoctor.jvm.base' version '{release-version}' } ---- @@ -190,6 +189,6 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.base") version "{revnumber}" + id("org.asciidoctor.jvm.base") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc similarity index 90% rename from docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc index e55824a2f..fab17ce1e 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-compatiblity-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-compatiblity-plugin.adoc @@ -1,4 +1,4 @@ -== Asciidoctor Compatibility Plugin += Asciidoctor Compatibility Plugin In order to help people upgrade a compatibility plugin has been kept which mostly behaves in the same way as the {asciidoctorj-name} plugins in the 1.5.x series [source,groovy,role="primary"] @@ -6,7 +6,7 @@ In order to help people upgrade a compatibility plugin has been kept which mostl .build.gradle ---- plugins { - id 'org.asciidoctor.convert' version '{revnumber}' + id 'org.asciidoctor.convert' version '{release-version}' } ---- @@ -15,7 +15,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.convert") version "{revnumber}" + id("org.asciidoctor.convert") version "{release-version}" } ---- @@ -64,4 +64,5 @@ sourceDir:: where the asciidoc sources are. sources:: specify which Asciidoctor source files to include by using an http://www.gradle.org/docs/current/javadoc/org/gradle/api/tasks/util/PatternSet.html[Ant-style PatternSet]. -NOTE: Even though the DSL remains the same with this task, the internals have been changed to use the same `JAVA_EXEC` mechanism of the `org.asciidoctor.jvm.convert` plugins. The problems which the 1.5.x series suffered with classpaths anions disappearing should now be a thing of the past. +NOTE: Even though the DSL remains the same with this task, the internals have been changed to use the same `JAVA_EXEC` mechanism of the `org.asciidoctor.jvm.convert` plugins. +The problems which the 1.5.x series suffered with classpaths anions disappearing should now be a thing of the past. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc b/docs/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc similarity index 93% rename from docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc rename to docs/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc index 9d0fe724f..ae8ed88c4 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-custom-extensions.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-custom-extensions.adoc @@ -1,10 +1,9 @@ -[[asciidoctorj-extensions,Adding custom {asciidoctorj-name} extensions]] -== Adding Custom Extensions += Adding Custom Extensions Starting with version 1.5.0 you were able to write your own Asciidoctor extensions in Groovy, or any other JVM language for that matter. Now with the 2.0.0 you have even more flexibility in that extensions can be applied on a per task basis on globally. There are several options available to make it happen. -=== As External Library +== As External Library This is the most versatile option, as it allows you to reuse the same extension in different projects. An external library is just like any other Java/Groovy project. You simply define a dependency using the `asciidoctor` configuration. @@ -39,8 +38,7 @@ tasks.withType { } ---- - -=== As Project Dependency +== As Project Dependency The next option is to host the extension project in a multi-project build. This allows for a much quicker development cycle as you don't have to publish the jar to a repository every time you make adjustments to the code. Take for example the @@ -81,7 +79,7 @@ The `extension` project is a sibling for `core`. The build file for the latter l .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } repositories { @@ -108,7 +106,7 @@ Alternatively you can add the project to the extension directly .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } asciidoctorj { @@ -119,7 +117,7 @@ asciidoctorj { In the less-common case where extension is not supplied via the default configuration, the latter shortcut will not work, and you will need to use the longer method described above. -=== As Inline Script +== As Inline Script The next option is to define extensions directly in the build script. This approach is based on the project asciidoctorj-groovy-dsl that allows to define Asciidoctor extensions in Groovy. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc similarity index 80% rename from docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc index 028213dd5..31e71df83 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-epub-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-epub-plugin.adoc @@ -1,5 +1,4 @@ -[[asciidoctorj-epub-plugin,{asciidoctorj-name} EPUB plugin]] -== The AsciidoctorEpub Plugin += {asciidoctorj-name} EPUB plugin INFO: As from version 3.3 support for KindleGen is dropped as Amazon no longer has the binary available for download. @@ -8,7 +7,7 @@ INFO: As from version 3.3 support for KindleGen is dropped as Amazon no longer h .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.epub' version '{revnumber}' + id 'org.asciidoctor.jvm.epub' version '{release-version}' } ---- @@ -17,12 +16,12 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.epub") version "{revnumber}" + id("org.asciidoctor.jvm.epub") version "{release-version}" } ---- When applying `org.asciidoctor.jvm.epub` it creates a single task of type `org.asciidoctor.gradle.jvm.epub.AsciidoctorEpubTask` which is then configured to: -* Output source to "${buildDir}/docs/asciidocEpub" +* Output source to "$\{buildDir}/docs/asciidocEpub" * Not to copy any resources to the output directory * It will set also a default version for `asciidoctorj-epub` artifact. To override set `asciidoctorj.epubVersion` or `asciidoctorEpub.asciidoctorj.epubVersion`. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc similarity index 77% rename from docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc index 7d41affb9..c4f18350f 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-gems-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-gems-plugin.adoc @@ -1,5 +1,4 @@ -[[asciidoctorj-gems-plugin,AsciidoctorJ GEMs plugin]] -== Ruby GEM support += AsciidoctorJ GEMs plugin GEM support is simplified via the `org.asciidoctor.jvm.gems` plugin. @@ -8,7 +7,7 @@ GEM support is simplified via the `org.asciidoctor.jvm.gems` plugin. .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.gems' version '{revnumber}' + id 'org.asciidoctor.jvm.gems' version '{release-version}' } repositories { @@ -35,6 +34,6 @@ asciidoctorj { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.gems") version "{revnumber}" + id("org.asciidoctor.jvm.gems") version "{release-version}" } ---- diff --git a/docs/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc new file mode 100644 index 000000000..52fad8cd9 --- /dev/null +++ b/docs/modules/ROOT/pages/asciidoctorj-leanpub-plugin.adoc @@ -0,0 +1,9 @@ += {asciidoctorj-name} Leanpub plugin + +When applying `org.asciidoctor.jvm.leanpub` it creates a single task of type `org.asciidoctor.gradle.jvm.epub.AsciidoctorLeanTask` which is then configured to: + +* Output source to "$\{buildDir}/docs/asciidocLeanpub". +* Set also a default version for `asciidoctor-leanpub-backend` artifact. +To override set `asciidoctorj.leanpubVersion` or `asciidoctorLeanpub.asciidoctorj.leanpubVersion`. + +If you use the traditional Dropbox mechanism of synchronising your writing to Dropbox you can apply the `org.asciidoctor.jvm.leanpub.dropbox-copy' plugin which will add a `copyAsciidocToDropbox` task which can copy your generated Leanpub content to the Dropbox folder which Leanpub has created for you. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc similarity index 88% rename from docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc index 8676d2e2d..49c9c910f 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-pdf-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-pdf-plugin.adoc @@ -1,13 +1,11 @@ -:AsciidoctorPdfTask-url: {groovydoc-jvm}/AsciidoctorPdfTask.html -[[asciidoctorj-pdf-plugin,AsciidoctorJ PDF plugin]] -== The AsciidoctorPdf Plugin += {asciidoctorj-pdf-name} plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.pdf' version '{revnumber}' + id 'org.asciidoctor.jvm.pdf' version '{release-version}' } ---- @@ -16,7 +14,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.pdf") version "{revnumber}" + id("org.asciidoctor.jvm.pdf") version "{release-version}" } ---- @@ -24,8 +22,8 @@ When applying `org.asciidoctor.jvm.pdf` it creates a single task of type `org.as The default task is named `asciidoctorPdf` and is configured to: -* Output source to "${buildDir}/docs/asciidocPdf" -* Not to copy any resources to the output directory +* Output source to "$\{buildDir}/docs/asciidocPdf". +* Not to copy any resources to the output directory. * It will set also a default version for `asciidoctorj-pdf` artifact. To override set `asciidoctorj.pdfVersion` or `asciidoctorPdf.asciidoctorj.pdfVersion`. The `AsciidoctorPdfTask` task type has the following additional methods: @@ -48,7 +46,7 @@ pdfThemes { } } ---- -<1> Local themes are registered using the `local` keyword and must be provided with a name +<1> Local themes are registered using the `local` keyword and must be provided with a name. <2> Directory for finding the theme. Specify a directory in any form acceptable to `project.file`. <3> Optional setting of the style name. If this is not set, the theme name provided previously will be used. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-plugin.adoc similarity index 61% rename from docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-plugin.adoc index 2fd0d9a16..3e318ebaf 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-plugin.adoc @@ -1,11 +1,11 @@ -== The New AsciidoctorJ Plugin += AsciidoctorJ Plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } ---- @@ -14,13 +14,13 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.convert") version "{revnumber}" + id("org.asciidoctor.jvm.convert") version "{release-version}" } ---- When applying `org.asciidoctor.jvm.convert` it creates a single task of type `org.asciidoctor.gradle.jvm.AsciidoctorTask` called `asciidoctor`. -By convention it sets the -* `sourceDir` to `src/docs/asciidoc` -* `outputDir` to `${buildDir}/docs/asciidoc` +By convention, it sets the +* `sourceDir` to `src/docs/asciidoc` +* `outputDir` to `$\{buildDir}/docs/asciidoc` diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc similarity index 90% rename from docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc index 15be8c7ba..c1554d1d4 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-revealjs-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorj-revealjs-plugin.adoc @@ -1,12 +1,11 @@ -[[asciidoctorj-revealjs-plugin,AsciidoctorJ Reveal.js plugin]] -== The AsciidoctorJ Reveal.js Plugin += AsciidoctorJ Reveal.js plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.revealjs' version '{revnumber}' + id 'org.asciidoctor.jvm.revealjs' version '{release-version}' } ---- @@ -15,7 +14,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.revealjs") version "{revnumber}" + id("org.asciidoctor.jvm.revealjs") version "{release-version}" } ---- @@ -24,7 +23,7 @@ When applying `org.asciidoctor.jvm.revealjs` support is added for creating slide * Create a task called `asciidoctorRevealJs`. * Create an extension called `revealjs` which is used for configuring the version of Reveal.js as well as a template. * Create an extension called `revealjsPlugins` which will allow for downloading additional Reveal.js plugins. -* Output source to "${buildDir}/docs/asciidocRevealJs" +* Output source to "$\{buildDir}/docs/asciidocRevealJs" * Copy all resources to the output directory including Reveal.js templates. * Apply the `org.asciidoctor.jvm.gems` plugin as GEM support is required. @@ -32,7 +31,7 @@ The `AsciidoctorRevealJSTask` task type has the following additional methods: [horizontal] revealjsOptions:: Configure special Reveal.js options. - Can be configured via Closure or Action. See <> for more details. + Can be configured via Closure or Action. See xref:#RevealJsOptions[] for more details. templateDir:: Location where the template directory will be located on disk before Asciidoctor processing starts. theme:: The Reveal.js theme to use. The theme must match one from the template. @@ -56,8 +55,8 @@ revealjs { If not specified, sensible defaults are provided. -=== Reveal.js Options [[RevealJsOptions]] +== Reveal.js Options Various options can be configured for Reveal.js. Although these can be set as attributes directly, it is far better to set them on the task as advantage can be taken of Gradle task caching and file resolving. @@ -109,7 +108,7 @@ processBar:: Display a presentation progress bar. Type is boolean. pushToHistory:: Push each slide change to the browser history. Type is boolean. -righttoLeft:: Change the presentation direction to be RTL. +rightToLeft:: Change the presentation direction to be RTL. Type is boolean. slideNumber:: Display the slide number of the current slide. Can be a `RevealJSOptions.SlideNumber`, a string value or a boolean. diff --git a/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc b/docs/modules/ROOT/pages/asciidoctorjs-plugin.adoc similarity index 58% rename from docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc rename to docs/modules/ROOT/pages/asciidoctorjs-plugin.adoc index 52c129450..1f8325f71 100644 --- a/docs/src/docs/asciidoc/parts/asciidoctorjs-plugin.adoc +++ b/docs/modules/ROOT/pages/asciidoctorjs-plugin.adoc @@ -1,12 +1,11 @@ -[[asciidoctorjs-plugin,{asciidoctorjs-name} plugin]] -== Working with Asciidoctor.js instead += Working with Asciidoctor.js instead -Instead of {asciidoctorj-name}, {asciidoctorjs-name} can be used as a rendering engine as from 3.0. +Instead of {asciidoctorj-name}, {asciidoctorjs-url}[{asciidoctorjs-name}] can be used as a rendering engine from 3.0. The configuration follows much the same as for {asciidoctorj-name}, but will a couple of differences. -* Only HTML is supported out of the box -* The configurating extension is called `asciidoctorjs` and is available at both task and project level. +* Only HTML is supported out of the box. +* The configuration extension is called `asciidoctorjs` and is available at both task and project level. * Docbook must be enabled via `asciidoctorjs.modules.docbook.use()`. * The implementation runs node.js under the hood, but the user does not have to install anything. The plugin suite takes care of everything. * Additional NPM modules can be added via `asciidoctorj.require`. diff --git a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc b/docs/modules/ROOT/pages/common-task-configuration.adoc similarity index 86% rename from docs/src/docs/asciidoc/parts/common-task-configuration.adoc rename to docs/modules/ROOT/pages/common-task-configuration.adoc index f25df4fbe..8e5c6808f 100644 --- a/docs/src/docs/asciidoc/parts/common-task-configuration.adoc +++ b/docs/modules/ROOT/pages/common-task-configuration.adoc @@ -1,11 +1,12 @@ -== Task Configuration += Task Configuration All Asciidoctor tasks will have the following methods and properties: .Properties and methods common all {asciidoctorj-name} tasks [horizontal] asciidoctorj:: a task extension which allows a task to extend of override global configuration for Asciidoctor tasks. - This allow extensive flexibility. Any thing that can be configured in the global `asciidoctorj` extension can also be configured here. + This allows extensive flexibility. + Any thing that can be configured in the global `asciidoctorj` extension can also be configured here. attributes:: A shortcut for `asciidoctorj.attributes` and `asciidoctorjs.attributes`. baseDir:: Base directory for asciidoctor document conversion and root document inclusion. The base directory will be the project directory by default, but can be set to any other directory. @@ -29,10 +30,12 @@ outputDir:: where generated docs go. Type: File, but any object convertible with `project.file` can be passed. Default: `$buildDir/asciidoc`. parallelMode:: Specifies whether each backend or other variant of a converting tasks should be run in parallel or sequential. - Sequential conversions might have less initialisation overhead, but may suffer from `gemPath` and extension pollution. Default: `true` (parallel). + Sequential conversions might have less initialisation overhead, but may suffer from `gemPath` and extension pollution. + Default: `true` (parallel). resources:: specify which additional files (image etc.) must be copied to output directory using a http://www.gradle.org/docs/current/javadoc/org/gradle/api/file/CopySpec.html[CopySpec]. -secondarySources: Specify which source files should be monitor for change. These are typically files which are included by top-level files as well as doctype files. +secondarySources:: Specify which source files should be monitored for change. + These are typically files which are included by top-level files as well as doctype files. Default: All files in sourceDir which matches `getDefaultSourceDocumentPattern()` as well as doctype files. sourceDir:: where the asciidoc sources are. Use either `sourceDir path`, `setSourceDir path` or `sourceDir=path` @@ -41,9 +44,13 @@ sourceDir:: where the asciidoc sources are. sources:: Specify which Asciidoctor source files to include as toplevel documents. It uses an http://www.gradle.org/docs/current/javadoc/org/gradle/api/tasks/util/PatternSet.html[Ant-style PatternSet]. useIntermediateWorkDir:: Use an intermediate work directory for sources ances. - Some extensions such as `ditaa` will write content into the source directory. In order to keep the project source directory pristine an intermediate work directory can be used. All sources and resources will be copied there prior the executing Asciidoctor. + Some extensions such as `ditaa` will write content into the source directory. + In order to keep the project source directory pristine an intermediate work directory can be used. + All sources and resources will be copied there prior the executing Asciidoctor. withIntermediateArtifacts:: Add intermediate artifacts to output directory. - If the document conversion process creates intermediate artifacts which needs to be added to the output directory, then the pattern set with a closure or `Action`. This implies `useIntermediateWorkDir`. An example of such a case is the use of `ditaa`. + If the document conversion process creates intermediate artifacts which needs to be added to the output directory, then the pattern set with a closure or `Action`. + This implies `useIntermediateWorkDir`. + An example of such a case is the use of `ditaa`. IMPORTANT: You will have to configure the properties for each plugin as they are not inherited from one to another. For example you will have to configure `languages` for both `org.asciidoctor.jvm.convert` and `org.asciidoctor.jvm.pdf` plugins if you want multi language pdf and html. @@ -61,7 +68,7 @@ backends:: the backends to use. separateOutputDirs:: specifies whether each backend should use a separate subfolder under `outputDir`. Default: `true` -=== Defining Sources +== Defining Sources The plugin will search for sources under `sourceDir`. Sources may have any of the following extensions in order to be discovered: @@ -104,7 +111,7 @@ tasks { Paths defined in this PatternSet are resolved relative to the `sourceDir`. -=== Processing Auxiliary Files +== Processing Auxiliary Files Some backends require that additional files be copied across. The most common example are images for HTML backends. For this the `resources` method is used. It is provided with a closure that configures an org.asciidoctor.gradle.jvm.epub.internal @@ -181,7 +188,7 @@ If you do not want this behaviour, then it can be turned off by doing copyNoResources() ---- -If you are using multiple languages and you have identical resource patterns for each languages within `sourceDir/${lang}` you need to explicitly declare those on a per-language basis: +If you are using multiple languages and you have identical resource patterns for each language within `sourceDir/$\{lang}` you need to explicitly declare those on a per-language basis: [source,groovy,role="primary"] .build.gradle @@ -199,11 +206,11 @@ resources 'es', { } ---- -=== Include directives and base directory +== Include directives and base directory These plugins do not change the way link:https://asciidoctor.org/docs/user-manual/#include-resolution[include::] directive works, but it is important to note how setting `baseDir` will affect top level includes. It is recommended that you always use `\{includedir}` as a prefix for the file path. This attribute is always set to the correct top-level folder where the sources will be located. -However it is not practical for everyone to use `\{includedir}` and as from 2.2.0 it is possible to add a strategy for controlling the base directory: +However, it is not practical for everyone to use `\{includedir}` and as from 2.2.0 it is possible to add a strategy for controlling the base directory: [source,groovy,role="primary"] .build.gradle @@ -220,13 +227,15 @@ asciidoctor { <3> The base directory will always the the same as the source directory. If an intermediate working directory is being used, the base directory will automatically point to that. <4> The base directory will be the same as the directory of each individual source file. -=== Docinfo processing +== Docinfo processing -When using the `docinfo` attribute with `html` and `docbook` backends, it is recommended that `baseDirFollowsSourceDir()` is always set. This will ensure that the docinfo files are picked up correctly from the same directory that is the source directory. +When using the `docinfo` attribute with `html` and `docbook` backends, it is recommended that `baseDirFollowsSourceDir()` is always set. +This will ensure that the docinfo files are picked up correctly from the same directory that is the source directory. -=== Source language support +== Source language support -Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. The Gradle plugin simplifies this scenario by allowing a structure such as +Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. +The Gradle plugin simplifies this scenario by allowing a structure such as [source] ---- @@ -247,7 +256,9 @@ asciidoctor { } ---- -Gradle will then process both the `en` and the `es` source set and output to the output directory using the same languages names. Intermediate working directories and multiple backends are also covered. In this case the `lang` attribute will be injected with the specific language as the value. +Gradle will then process both the `en` and the `es` source set and output to the output directory using the same languages names. +Intermediate working directories and multiple backends are also covered. +In this case the `lang` attribute will be injected with the specific language as the value. It is also possible to specify additional attributes that will only be added when a specific language is processed @@ -266,11 +277,12 @@ asciidoctorjs { // <2> <1> Configuration when using {asciidoctorj-name} <2> Configuration when using {asciidoctorjs-name} -=== Choosing a Process Mode for {asciidoctorj-name} +== Choosing a Process Mode for {asciidoctorj-name} All {asciidoctorj-name}-based tasks can control how Asciidoctor conversions are being run via the `inProcess` property. This is early days, and a choice for your build will depend very much on your context, but the following has already become clear: * `IN_PROCESS` and `OUT_OF_PROCESS` should theoretically run faster, especially if you continuously rebuild the same documentation. Gradle workers are the underlying implementation for these two options * The safe option is always `JAVA_EXEC`. For lower memory consumption this is by far the safer option. (It is also the only way we can get the Windows-based tests for this plugin to complete on Appveyor & Travis CI). It you run a lot of builds the penalty start-up time might become an issue for you. -NOTE: In certain cases the plugin will overrule your choice as it has some built-in rules for special cases. In such cases it will log a warning that it has done that. +NOTE: In certain cases the plugin will overrule your choice as it has some built-in rules for special cases. +In such cases it will log a warning that it has done that. diff --git a/docs/src/docs/asciidoc/parts/compatibility.adoc b/docs/modules/ROOT/pages/compatibility.adoc similarity index 92% rename from docs/src/docs/asciidoc/parts/compatibility.adoc rename to docs/modules/ROOT/pages/compatibility.adoc index 0da929c7c..d3335a649 100644 --- a/docs/src/docs/asciidoc/parts/compatibility.adoc +++ b/docs/modules/ROOT/pages/compatibility.adoc @@ -1,4 +1,4 @@ -== Compatibility += Compatibility This collection of plugins requires at least Gradle 4.9, JDK 11.0 and AsciidoctorJ 2.0.0 to run. If you need prior Gradle, JDK or {asciidoctorj-name} support please use a plugin from the 1.5.x or 1.6.x release series. diff --git a/docs/src/docs/asciidoc/parts/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc similarity index 79% rename from docs/src/docs/asciidoc/parts/docinfo.adoc rename to docs/modules/ROOT/pages/docinfo.adoc index a5c4c5a66..86694335d 100644 --- a/docs/src/docs/asciidoc/parts/docinfo.adoc +++ b/docs/modules/ROOT/pages/docinfo.adoc @@ -1,4 +1,4 @@ -== Extra content for HTML & Docbook backends += Extra content for HTML & Docbook backends You may need to include extra content into the head of the exported document. For example, you might want to include jQuery inside the `` element of the HTML export. @@ -16,9 +16,9 @@ Then, add the `docinfo1` attribute to the attributes list in the previous exampl .build.gradle ---- asciidoctorj { // <1> - attribute 'docinfo1', '' + attribute 'docinfo', '' } ---- <1> Substitute `asciidoctorjs` if you are using the {asciidoctorjs-name} engine. -See link:{asciidoctor-userguide}#docinfo-file[{asciidoctor-userguide-name}] for more information on `docinfo` and friends. +See link:{asciidoctor-docs}/docinfo/[Asciidoctor's Docinfo File] for more information on `docinfo` and friends. diff --git a/docs/src/docs/asciidoc/parts/exporting-slides.adoc b/docs/modules/ROOT/pages/exporting-slides.adoc similarity index 73% rename from docs/src/docs/asciidoc/parts/exporting-slides.adoc rename to docs/modules/ROOT/pages/exporting-slides.adoc index 5b3690acc..db8f645d3 100644 --- a/docs/src/docs/asciidoc/parts/exporting-slides.adoc +++ b/docs/modules/ROOT/pages/exporting-slides.adoc @@ -1,5 +1,5 @@ [[decktape-plugin,Decktape plugin]] -== Exporting Slides += Exporting Slides If you have created HTML slides via an Asciidoctor task you can export them to PDF/PNG/JPG. @@ -34,9 +34,9 @@ task standalonePdfConverter(type: DeckTapeTask) { <3> If screenshots are activated, then screenshot images of the slides are also produced. <4> Image format. PMG and JPG are supported. <5> Width and height of the exported slides. -<6> Range of slides to export. By default all are exported. +<6> Range of slides to export. By default, all are exported. -=== Combining with Reveal.js plugin +== Combining with Reveal.js plugin If you do @@ -45,8 +45,8 @@ If you do .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.revealjs' version '{revnumber}' - id 'org.asciidoctor.decktape.base' version '{revnumber}' + id 'org.asciidoctor.jvm.revealjs' version '{release-version}' + id 'org.asciidoctor.decktape.base' version '{release-version}' } ---- @@ -55,11 +55,11 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.revealjs") version "{revnumber}" - id("org.asciidoctor.decktape.base") version "{revnumber}" + id("org.asciidoctor.jvm.revealjs") version "{release-version}" + id("org.asciidoctor.decktape.base") version "{release-version}" } ---- -a little bit of _magic_ happens. A task called on `asciidoctorRevealJsExport` is created on demand from a rule and all of the appropriate properties are set on it so that it can export slides created by the `asciidoctorRevealJs` task. +a little bit of _magic_ happens. A task called on `asciidoctorRevealJsExport` is created on demand from a rule and all the appropriate properties are set on it so that it can export slides created by the `asciidoctorRevealJs` task. You can configure the `asciidoctorRevealJsExport` task like any other `DeckTapeTask`. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 000000000..2edc06d37 --- /dev/null +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,10 @@ += Asciidoctor Gradle Plugin Suite +:navtitle: Introduction + +The {doctitle} is the official means of using {asciidoctor-url}[Asciidoctor] to convert all your {asciidoc-url}[AsciiDoc] documentation using {gradle-url}[Gradle]. + +This started as a port of the {asciidoctor-maven-plugin-url}[asciidoctor-maven-plugin-name] project founded by {lightguard} and relies on {asciidoctorj-url}[{asciidoctorj-name}] which was founded by {lordofthejars}. +In fact the 1.5.x series of the {plugin-name} can still be considered a port. + +However, with 2.x series came a complete departure with functionality far exceeding any lightweight markup plugins for any other build tool. +With the 3.x serious allows for even more flexibility and options for the creation of a true DocuOps pipeline by bringing together Gradle as a powerful and generic build tool, and Asciidoctor as an agile and lightweight document generator. diff --git a/docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc b/docs/modules/ROOT/pages/kindlegen-plugin.adoc similarity index 85% rename from docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc rename to docs/modules/ROOT/pages/kindlegen-plugin.adoc index 8542a8049..dfb179000 100644 --- a/docs/src/docs/asciidoc/parts/kindlegen-plugin.adoc +++ b/docs/modules/ROOT/pages/kindlegen-plugin.adoc @@ -1,11 +1,11 @@ -== Kindlegen plugin += Kindlegen plugin [source,groovy,role="primary"] [subs=attributes+] .build.gradle ---- plugins { - id 'org.asciidoctor.kindlegen.base' version '{revnumber}' + id 'org.asciidoctor.kindlegen.base' version '{release-version}' } ---- @@ -14,7 +14,7 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.kindlegen.base") version "{revnumber}" + id("org.asciidoctor.kindlegen.base") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/quick-start.adoc b/docs/modules/ROOT/pages/quick-start.adoc similarity index 64% rename from docs/src/docs/asciidoc/parts/quick-start.adoc rename to docs/modules/ROOT/pages/quick-start.adoc index 237be3cfa..90ef2c6e4 100644 --- a/docs/src/docs/asciidoc/parts/quick-start.adoc +++ b/docs/modules/ROOT/pages/quick-start.adoc @@ -1,4 +1,4 @@ -== Quick Start += Quick Start To start you need to use one of the plugins from the following Gradle snippet @@ -7,7 +7,7 @@ To start you need to use one of the plugins from the following Gradle snippet .build.gradle ---- plugins { - id 'org.asciidoctor.jvm.convert' version '{revnumber}' + id 'org.asciidoctor.jvm.convert' version '{release-version}' } ---- @@ -16,6 +16,6 @@ plugins { .build.gradle.kts ---- plugins { - id("org.asciidoctor.jvm.convert") version "{revnumber}" + id("org.asciidoctor.jvm.convert") version "{release-version}" } ---- diff --git a/docs/src/docs/asciidoc/parts/upgrading.adoc b/docs/modules/ROOT/pages/upgrading.adoc similarity index 93% rename from docs/src/docs/asciidoc/parts/upgrading.adoc rename to docs/modules/ROOT/pages/upgrading.adoc index ed352524b..96e079df8 100644 --- a/docs/src/docs/asciidoc/parts/upgrading.adoc +++ b/docs/modules/ROOT/pages/upgrading.adoc @@ -1,5 +1,4 @@ - -== Upgrading From Older Versions of Asciidoctor += Upgrading From Older Versions of Asciidoctor NOTE: If you are still on a 1.5/1.6 version of the plugin, upgrade to the latest 2.x version first. @@ -21,11 +20,11 @@ If you have {asciidoctorj-name} binary extensions you'll need to recompile them Substitutable attributes means that the build script author can change those attributes by setting them explicitly. -=== Asciidoctor compatibility tasks +== Asciidoctor compatibility tasks The Asciidoctor compatibility task has been removed. You need to use the Asciidoctor task from `org.asciidoctor.jvm.convert` instead. -=== GEMs +== GEMs If you used external GEMs via the http://jruby-gradle.github.io/[JRuby Gradle plugin], you should switch over to using `org.asciidoctor.jvm.gems` instead. You should also use the `asciidoctorGems` configuration rather than the `gems` configuration. Tasks should not depend on `JRubyPrepare`, but on `AsciidoctorGemsPrepare` instead. @@ -49,7 +48,7 @@ then change it to [subs=attributes+] ---- plugins { - id 'org.asciidoctor.jvm.gems' version '{revnumber}' + id 'org.asciidoctor.jvm.gems' version '{release-version}' } repositories { @@ -57,20 +56,20 @@ repositories { } ---- -=== Reveal.js +== Reveal.js Follows the same guidelines as for GEMS above. -=== Configurations +== Configurations The `asciidoctor` configuration is no longer available. If you used that before to make artifacts available on the classpath you should use the `configurations` method on the task to add them. If you used it to manipulate versions of {asciidoctorj-name} and JRuby then you should rather use the explicit versions settings on `asciidoctorj`. -=== Multiple Asciidoctor tasks +== Multiple Asciidoctor tasks If you have more than one Asciidoctor task, decide which `options`, `attributes` and `requires` should go in the `asciidoctorj` global project extension block and which should be customised within the tasks `asciidoctor` extension block. Importantly, you probably did `import org.asciidoctor.gradle.AsciidoctorTask`. You will need to change that to `import org.asciidoctor.gradle.jvm.AsciidoctorTask`. -=== Extensions +== Extensions Extensions on the Gradle classpath are no longer detected. You need to declare them explicitly. This includes any extensions created in `buildSrc`. diff --git a/docs/modules/appendices/nav.adoc b/docs/modules/appendices/nav.adoc new file mode 100644 index 000000000..573c01894 --- /dev/null +++ b/docs/modules/appendices/nav.adoc @@ -0,0 +1,4 @@ +* Appendices +** xref:tips-and-tricks.adoc[] +** xref:known-limitations.adoc[] +** xref:hacking.adoc[] diff --git a/docs/modules/appendices/pages/hacking.adoc b/docs/modules/appendices/pages/hacking.adoc new file mode 100644 index 000000000..18d3d9f65 --- /dev/null +++ b/docs/modules/appendices/pages/hacking.adoc @@ -0,0 +1,10 @@ += Development +:development-branch: development-4.x + +`master` now represents the code for the latest 4.x release of these plugins. + +Development for 4.x is against the link:{project-repo-url}/tree/{development-branch}[{development-branch}] branch. +PRs are preferably taking against this branch. + +The 3.x series of the plugin is now in maintenance only mode. +PRs for that should be raised against the link:{project-repo-url}/tree/maintenance-3.x[maintenance-3.x] branches. diff --git a/docs/src/docs/asciidoc/appendix/known-limitations.adoc b/docs/modules/appendices/pages/known-limitations.adoc similarity index 95% rename from docs/src/docs/asciidoc/appendix/known-limitations.adoc rename to docs/modules/appendices/pages/known-limitations.adoc index 10f6ffff1..477ce526c 100644 --- a/docs/src/docs/asciidoc/appendix/known-limitations.adoc +++ b/docs/modules/appendices/pages/known-limitations.adoc @@ -1,5 +1,4 @@ -[appendix] -== Known Issues += Known Issues These are the main ones we know about: diff --git a/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc b/docs/modules/appendices/pages/tips-and-tricks.adoc similarity index 86% rename from docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc rename to docs/modules/appendices/pages/tips-and-tricks.adoc index a153b89e6..f3d7d4258 100644 --- a/docs/src/docs/asciidoc/appendix/tips-and-tricks.adoc +++ b/docs/modules/appendices/pages/tips-and-tricks.adoc @@ -1,7 +1,6 @@ -[appendix] -== Tips & Tricks += Tips & Tricks -=== Issues with plugins that modify project.version +== Issues with plugins that modify project.version Plugins such as https://github.com/nebula-plugins/nebula-release-plugin[Nebula Release] and https://github.com/ajoberstar/reckon[Reckon] modify `project.version` with a non-serialisable object. This breaks the build. @@ -14,7 +13,7 @@ asciidoctorj { } ---- -=== Pre-process and post-process +== Pre-process and post-process To make your own custom actions before or after asciidoctor processing, use `doFirst` and `doLast`. Check out chapters https://docs.gradle.org/current/userguide/tutorial_using_tasks.html[14] and https://docs.gradle.org/current/userguide/more_about_tasks.html[17] in the Gradle docs to learn about the various actions you can perform. @@ -43,7 +42,7 @@ asciidoctor.doLast { } ---- -=== Using Pygments source highlighter +== Using Pygments source highlighter NOTE: You need to have Python 2.x installed on a system or in a container for Pygments to work. @@ -51,8 +50,8 @@ NOTE: You need to have Python 2.x installed on a system or in a container for Py [subs=attributes+] ---- plugins { - id 'org.asciidoctor.jvm.pdf' version '{revnumber}' - id 'org.asciidoctor.jvm.gems' version '{revnumber}' + id 'org.asciidoctor.jvm.pdf' version '{release-version}' + id 'org.asciidoctor.jvm.gems' version '{release-version}' } repositories { @@ -74,4 +73,3 @@ asciidoctorPdf { } } ---- - diff --git a/docs/modules/file.adoc b/docs/modules/file.adoc new file mode 100644 index 000000000..7b57bd29e --- /dev/null +++ b/docs/modules/file.adoc @@ -0,0 +1 @@ +some text diff --git a/docs/publish-docs-from-travis b/docs/publish-docs-from-travis deleted file mode 100755 index 2408c9b63..000000000 --- a/docs/publish-docs-from-travis +++ /dev/null @@ -1,15 +0,0 @@ -#!/usr/bin/env bash - -set -e - -$(dirname $(dirname $0))/gradlew groovydoc && \ - cd $(dirname $0) && \ - ./gradlew --console=plain -q combineDocs - -if [[ "${TRAVIS_PULL_REQUEST}" == "false" && "${TRAVIS_REPO_SLUG}" == "asciidoctor/asciidoctor-gradle-plugin" ]] ; then - set -x - ./gradlew --console=plain :antora:publishDocs :gh-pages:publishDocs \ - -Dorg.ajoberstar.grgit.auth.username=$GITHUB_PUBLISH_USER \ - -Dorg.ajoberstar.grgit.auth.password=$GITHUB_PUBLISH_KEY \ - -Dorg.ajoberstar.grgit.auth.force=hardcoded -fi \ No newline at end of file diff --git a/docs/settings.gradle b/docs/settings.gradle deleted file mode 100644 index 12293e956..000000000 --- a/docs/settings.gradle +++ /dev/null @@ -1,6 +0,0 @@ -rootProject.name='asciidoctor-gradle-docs' - -includeBuild('..') -include 'gh-pages' -// Removes antora, causes issue with gh-pages and git-publish plugin. Causing commits to delete files. -// include 'antora' diff --git a/docs/src/docs/asciidoc/appendix/hacking.adoc b/docs/src/docs/asciidoc/appendix/hacking.adoc deleted file mode 100644 index 5d28834f7..000000000 --- a/docs/src/docs/asciidoc/appendix/hacking.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[appendix] -== Development - -NOTE: The `master` branch represents the code for the latest 2.x release of these plugins. Development for for 2.x is against the link:https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/development-2.0[development-2.0] branch. PRs are preferably taking against that branch. The 1.5.x & 1.6.x series of the plugin is now in maintenance only mode. PRs for these should be raised against the https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-1.5[maintenance-1.5] and https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-1.6[maintenance-1.6]branch. diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/src/docs/asciidoc/attributes.adoc deleted file mode 100644 index 222475efc..000000000 --- a/docs/src/docs/asciidoc/attributes.adoc +++ /dev/null @@ -1,25 +0,0 @@ -:asciidoc-url: http://asciidoc.org -:asciidoctor-docs: http://asciidoctor.org/docs/ -:asciidoctor-userguide: {asciidoctor-docs}user-manual/ -:asciidoctor-userguide-name: Asciidoctor User Manual -:asciidoctor-maven-plugin: https://github.com/asciidoctor/asciidoctor-maven-plugin[Asciidoctor Maven Plugin] -:asciidoctor-url: http://asciidoctor.org -:asciidoctorj: https://github.com/asciidoctor/asciidoctorj -:asciidoctorj-name: AsciidoctorJ -:asciidoctorj-epub-name: Asciidoctorj-EPUB -:asciidoctorj-pdf-name: Asciidoctorj-PDF -:asciidoctorj-pdf-leanpub: Asciidoctorj Leanpub -:asciidoctorjs-name: Asciidoctor.js -:gradle-url: http://gradle.org/ -:icons: font -:issues: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/ -:issues-asciidoctorj: https://github.com/asciidoctor/asciidoctorj/issues/ -:issues-jruby: https://github.com/asciidoctor/asciidoctorj/issues/ -:jruby-name: JRuby -:kotlindsl: https://github.com/gradle/kotlin-dsl[Gradle Kotlin DSL] -:lightguard: https://github.com/LightGuard[Jason Porter] -:linkattrs: -:lordofthejars: https://github.com/lordofthejars[Alex Soto] -:plugin-name: Asciidoctor Gradle plugin -:project-full-path: asciidoctor/asciidoctor-gradle-plugin -:project-name: asciidoctor-gradle-plugin diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc deleted file mode 100644 index 526767f7e..000000000 --- a/docs/src/docs/asciidoc/index.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= Asciidoctor Gradle Plugin Suite -include::attributes.adoc[] -ifdef::env-idea[] -:toc: preamble -endif::[] -ifeval::[{env}!=idea] -:toc: right -endif::[] - -The {doctitle} is the official means of using {asciidoctor-url}[Asciidoctor] to convert all your {asciidoc-url}[AsciiDoc] documentation using {gradle-url}[Gradle]. - -This started as a port of the {asciidoctor-maven-plugin} project founded by {lightguard} and relies on {asciidoctorj}[{asciidoctorj-name}] which was founded by {lordofthejars}. -In fact the 1.5.x series of the {plugin-name} can still be considered a port. However, with 2.x series came a complete departure with functionality far exceeding any lightweight markup plugins for any other build tool. -With the 3.x serious allows for even more flexibility and options for the creation of a true DocuOps pipeline by bringing together Gradle as a powerful and generic build tool, and Asciidoctor as an agile and lightweight document generator. - -include::parts/compatibility.adoc[] - -include::parts/quick-start.adoc[] - -include::parts/common-task-configuration.adoc[] - -include::parts/asciidoctorj-base-plugin.adoc[] - -include::parts/asciidoctorj-plugin.adoc[] - -include::parts/asciidoctorj-pdf-plugin.adoc[] - -include::parts/asciidoctorj-epub-plugin.adoc[] - -include::parts/asciidoctorj-revealjs-plugin.adoc[] - -// include::parts/asciidoctorj-leanpub-plugin.adoc[] - -include::parts/asciidoctor-diagram.adoc[] - -include::parts/asciidoctorj-gems-plugin.adoc[] - -//include::parts/kindlegen-plugin.adoc[] - -include::parts/asciidoctorj-custom-extensions.adoc[] - -include::parts/asciidoctorjs-plugin.adoc[] - -include::parts/asciidoctoreditorconfig-plugin.adoc[] - -include::parts/docinfo.adoc[] - -include::parts/upgrading.adoc[] - -include::appendix/tips-and-tricks.adoc[] - -include::appendix/known-limitations.adoc[] - -include::appendix/hacking.adoc[] diff --git a/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc b/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc deleted file mode 100644 index 1cac5bd7f..000000000 --- a/docs/src/docs/asciidoc/parts/asciidoctorj-leanpub-plugin.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[asciidoctorj-leanpub-plugin,{asciidoctorj-name} Leanpub plugin]] -== The AsciidoctorLeanpub Plugin - -When applying `org.asciidoctor.jvm.leanpub` it creates a single task of type `org.asciidoctor.gradle.jvm.epub.AsciidoctorLeanTask` which is then configured to: - -* Output source to "${buildDir}/docs/asciidocLeanpub" -* Set also a default version for `asciidoctor-leanpub-backend` artifact. To override set `asciidoctorj.leanpubVersion` or `asciidoctorLeanpub.asciidoctorj.leanpubVersion`. - -If you use the traditional Dropbox mechanism of synchronising your writing to Dropbox you can apply the `org.asciidoctor.jvm.leanpub.dropbox-copy' plugn which will add a `copyAsciidocToDropbox` task which can copy your generated Leanpub content to the Dropbox folder which Leanpub has created for you. diff --git a/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy b/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy index 1ca8af30f..024ca885b 100644 --- a/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy +++ b/jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy @@ -484,7 +484,8 @@ class AsciidoctorJExtension extends AbstractImplementationEngineExtension { tag::extension-property[] options:: {asciidoctorj-name} options. Use `options` to append and `setOptions` to replace any current options with a new set. - Options are evaluated as late as possible. See <> for more details. + Options are evaluated as late as possible. + See <> for more details. end::extension-property[] ------------------------- */