From 6f21ce56fece86fbf6dbfc49231542ad9e310310 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Tue, 5 Mar 2024 22:09:32 +0100 Subject: [PATCH] Prepare appendices Antora module * Update hacking with branch description from README --- docs/antora/antora.yml | 3 +- docs/antora/docs/modules/ROOT/nav.adoc | 6 +- .../modules/appendices/pages/hacking.adoc | 10 +++ .../appendices/pages/known-limitations.adoc | 9 +++ .../appendices/pages/tips-and-tricks.adoc | 75 +++++++++++++++++++ docs/src/docs/asciidoc/appendix/hacking.adoc | 9 ++- docs/src/docs/asciidoc/attributes.adoc | 3 +- docs/src/docs/asciidoc/index.adoc | 4 +- 8 files changed, 112 insertions(+), 7 deletions(-) create mode 100644 docs/antora/docs/modules/appendices/pages/hacking.adoc create mode 100644 docs/antora/docs/modules/appendices/pages/known-limitations.adoc create mode 100644 docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc diff --git a/docs/antora/antora.yml b/docs/antora/antora.yml index 6ccfd8187..6f1aaba50 100644 --- a/docs/antora/antora.yml +++ b/docs/antora/antora.yml @@ -4,8 +4,9 @@ version: 4.0 asciidoc: attributes: release-version: 4.0.2 - project-name: asciidoctor-gradle-plugin project-full-path: asciidoctor/asciidoctor-gradle-plugin + project-name: asciidoctor-gradle-plugin + project-repo-url: asciidoctor-gradle-plugin plugin-name: Asciidoctor Gradle plugin asciidoc-url: https://asciidoc.org asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest diff --git a/docs/antora/docs/modules/ROOT/nav.adoc b/docs/antora/docs/modules/ROOT/nav.adoc index 1950d77c5..3974edcf5 100644 --- a/docs/antora/docs/modules/ROOT/nav.adoc +++ b/docs/antora/docs/modules/ROOT/nav.adoc @@ -1,4 +1,5 @@ * xref:compatibility.adoc[] +* xref:compatibility.adoc[] * xref:quick-start.adoc[] * xref:common-task-configuration.adoc[] * xref:asciidoctorj-base-plugin.adoc[] @@ -6,11 +7,12 @@ * xref:asciidoctorj-pdf-plugin.adoc[] * xref:asciidoctorj-epub-plugin.adoc[] * xref:asciidoctorj-revealjs-plugin.adoc[] -* xref:asciidoctorj-leanpub-plugin.adoc[] +// * xref:asciidoctorj-leanpub-plugin.adoc[] * xref:asciidoctor-diagram.adoc[] * xref:asciidoctorj-gems-plugin.adoc[] -//xref:kindlegen-plugin.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/antora/docs/modules/appendices/pages/hacking.adoc b/docs/antora/docs/modules/appendices/pages/hacking.adoc new file mode 100644 index 000000000..ecfc718ef --- /dev/null +++ b/docs/antora/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:https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-3.x[maintenance-3.x] branches. diff --git a/docs/antora/docs/modules/appendices/pages/known-limitations.adoc b/docs/antora/docs/modules/appendices/pages/known-limitations.adoc new file mode 100644 index 000000000..477ce526c --- /dev/null +++ b/docs/antora/docs/modules/appendices/pages/known-limitations.adoc @@ -0,0 +1,9 @@ += Known Issues + +These are the main ones we know about: + +* EPUB3 + KF8 in one task. 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 {issues-asciidoctorj}659[{asciidoctorj-name} #659] & {issues-jruby}4943[{jruby-name} #4943]. +* Does not work with JDK9 (but does with JDK10). +* DeckTape export to JPG/PNG does not work on Windows (issues-asciidoctorj}[{asciidoctorj-name} #381] & https://github.com/astefanutti/decktape/issues[Decktape #181]). diff --git a/docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc b/docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc new file mode 100644 index 000000000..f3d7d4258 --- /dev/null +++ b/docs/antora/docs/modules/appendices/pages/tips-and-tricks.adoc @@ -0,0 +1,75 @@ += Tips & Tricks + +== 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. + +The safest workaround is to set the `revnumber` attribute to a delayed evaluation of `project.version` in your build: + +[source,groovy] +---- +asciidoctorj { + attributes revnumber : { project.version.toString() } +} +---- + +== 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. + +[source,groovy] +.build.gradle +---- +asciidoctor.doFirst { + // pre-process +} +asciidoctor.doLast { + // post-process +} +---- + +As an example, here's how to copy the generated `index.html` file to the root of the project. This is useful in Windows systems where asciidoctor can't output directly to the root. + +[source,groovy] +.build.gradle +---- +asciidoctor.doLast { + copy { + from 'build/docs/html5' + into "$projectDir" + include 'index.html' + } +} +---- + +== Using Pygments source highlighter + +NOTE: You need to have Python 2.x installed on a system or in a container for Pygments to work. + +[source,groovy] +[subs=attributes+] +---- +plugins { + id 'org.asciidoctor.jvm.pdf' version '{release-version}' + id 'org.asciidoctor.jvm.gems' version '{release-version}' +} + +repositories { + jcenter() + ruby.gems() +} + +dependencies { + asciidoctorGems 'rubygems:pygments:1.2.1' +} + +asciidoctorPdf { + dependsOn asciidoctorGemsPrepare + sourceDir 'docs' + + asciidoctorj { + requires 'pygments' + attributes 'source-highlighter' : 'pygments' + } +} +---- diff --git a/docs/src/docs/asciidoc/appendix/hacking.adoc b/docs/src/docs/asciidoc/appendix/hacking.adoc index e54682de0..6d9f2f6b4 100644 --- a/docs/src/docs/asciidoc/appendix/hacking.adoc +++ b/docs/src/docs/asciidoc/appendix/hacking.adoc @@ -1,4 +1,11 @@ [appendix] = Development +:development-branch: development-4.x -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. +`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:https://github.com/asciidoctor/asciidoctor-gradle-plugin/tree/maintenance-3.x[maintenance-3.x] branches. diff --git a/docs/src/docs/asciidoc/attributes.adoc b/docs/src/docs/asciidoc/attributes.adoc index 9750e96d5..797d52847 100644 --- a/docs/src/docs/asciidoc/attributes.adoc +++ b/docs/src/docs/asciidoc/attributes.adoc @@ -1,5 +1,6 @@ -:project-name: asciidoctor-gradle-plugin :project-full-path: asciidoctor/asciidoctor-gradle-plugin +:project-name: asciidoctor-gradle-plugin +:project-repo-url: asciidoctor-gradle-plugin :plugin-name: Asciidoctor Gradle plugin :asciidoc-url: https://asciidoc.org :asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index 17251c2ad..86473b354 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -33,13 +33,13 @@ include::parts/asciidoctorj-epub-plugin.adoc[] include::parts/asciidoctorj-revealjs-plugin.adoc[] -//! include::parts/asciidoctorj-leanpub-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/kindlegen-plugin.adoc[] include::parts/asciidoctorj-custom-extensions.adoc[]