かんがるーさんの日記

最近自分が興味をもったものを調べた時の手順等を書いています。今は Spring Boot をいじっています。

Asciidoctor+Gradle の環境で AsciiDoc 形式のドキュメントから HTML ファイルを生成してみる

Translate to English
https://translate.google.com/translate?sl=auto&tl=en&u=https%3A%2F%2Fksby.hatenablog.com%2Fentry%2F2021%2F01%2F06%2F003807

概要

記事一覧はこちらです。

Spring Boot Reference Documentation が AsciiDoc 形式のドキュメントで記述されていることは知っていたのですが、これまで AsciiDoc 形式で記述したことがありませんでした。JUnit 5 のドキュメント やこの前 Spring Boot 2.2.x の Web アプリを 2.3.x へバージョンアップする ( 番外編 )( IntelliJ IDEA の docToolchain/diagrams.net-intellij-plugin を追加する ) でインストールした diagrams.net-intellij-plugin のドキュメント も AsciiDoc で記述されており、興味が湧いたので使い方を調べてみます。

AsciiDoc でドキュメントを生成するツールとして Asciidoctor があり、Asciidoctor には Gradle の Plugin が存在するので、Asciidoctor+Gradle で環境を構築します。

参照したサイト・書籍

  1. AsciiDoc Home Page
    https://asciidoc.org/

  2. Asciidoctor
    https://asciidoctor.org/

  3. AsciiDoc Writer’s Guide
    https://asciidoctor.org/docs/asciidoc-writers-guide/

  4. Asciidoctor User Manual
    https://asciidoctor.org/docs/user-manual/

  5. AsciiDoc Syntax Quick Reference
    https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

  6. AsciiDoc Recommended Practices
    https://asciidoctor.org/docs/asciidoc-recommended-practices/

  7. asciidoctor / asciidoctor
    https://github.com/asciidoctor/asciidoctor

  8. Asciidoctor Gradle Plugin Suite v3.1.0
    https://asciidoctor.github.io/asciidoctor-gradle-plugin/master/

  9. Java: How to resolve java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException
    https://stackoverflow.com/questions/43574426/java-how-to-resolve-java-lang-noclassdeffounderror-javax-xml-bind-jaxbexceptio

  10. Using the JDK_JAVA_OPTIONS Launcher Environment Variable
    https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE

目次

  1. ksbysample-asciidoctor プロジェクトを作成する
  2. build.gradle を記述する
  3. src/docs/asciidoc の下に index.adoc を作成する
  4. AsciiDoc Plugin をインストールする
  5. asciidoctor タスクを実行して index.html を生成する
  6. asciidoctor タスク実行時に WARNING メッセージが出力されないようにする
  7. html タグの lang 属性を ja にする
  8. シンタックスハイライトを有効にする
  9. asciidoctor タスクで実行する java.exe のコマンドで -Xverify:none、-XX:TieredStopAtLevel=1 オプションを指定して高速化する

手順

ksbysample-asciidoctor プロジェクトを作成する

  1. Github で ksbysample-asciidoctor レポジトリ を作成します。
  2. D:\project-springboot\ksbysample-asciidoctor に clone します。
  3. ksbysample-webapp-lending プロジェクトから Gradle Wrapper のファイルをコピーします（コピーした gradle のバージョンは 6.5.1）。
  4. コマンドプロンプトから以下のコマンドを実行して Gradle を 6.5.1 → 6.7.1 へバージョンアップします。
    • gradlew wrapper --gradle-version=6.7.1
    • gradlew --version
    • gradlew wrapper
  5. gradlew init を実行します。選択肢は 1: basic、1: groovy を選択し、Project name は何も入力せずに Enter キーを押します。
  6. プロジェクトのルートディレクトリの下に src/docs/asciidoc ディレクトリを作成します。
  7. .gitignore に以下の内容を記述します。
# Gradle
.gradle/
build/

# Intellij project files
*.iml
*.ipr
*.iws
.idea/

build.gradle を記述する

build.gradle に以下の内容を記述します。

plugins {
    id "org.asciidoctor.jvm.convert" version "3.3.0"
}

repositories {
    mavenCentral()
}

asciidoctor {
    sourceDir file("src/docs/asciidoc")
    sources {
        include "index.adoc"
    }
}
  • plugins block に id "org.asciidoctor.jvm.convert" version "3.3.0" を記述します。Asciidoctor Gradle Plugin Suite の Quick Start に記載されていたバージョンは 3.1.0 ですが、Search Gradle plugins で検索すると 3.3.0 でしたので 3.3.0 にします。
  • asciidoctor block を記述します。Defining Sources の build.gradle のサンプルを参考に、outputDir は書かなくても build/docs/asciidoc の下に出力してくれるようなので省きました。

Gradle Tool Window 左上の「Reload All Gradle Projects」ボタンをクリックして更新すると、documentation の下に asciidoctor タスクが表示されます。

f:id:ksby:20210103180101p:plain

src/docs/asciidoc の下に index.adoc を作成する

src/docs/asciidoc の下に index.adoc を作成し、https://asciidoctor.org/ の右上のサンプルをそのままコピー＆ペーストします。また java のシンタックスハイライトを確認したいので、java の簡単なコードも追加しておきます（---- は Delimited blocks 参照）。

= Hello, AsciiDoc!
Doc Writer <doc@example.com>

An introduction to http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

[source,java]
----
public class Person {
    private String name;
        public Person(String name) {
        this.name = name;
    }
}
----

AsciiDoc Plugin をインストールする

IntelliJ IDEA で AsciiDoc 形式のドキュメントの編集をサポートしてくれる AsciiDoc Plugin をインストールします。

f:id:ksby:20210103191845p:plain

Plugin をインストールすると右側に Preview が表示されるようになります（ただし Doc Writer <doc@example.com> は表示されませんでした）。

f:id:ksby:20210105232706p:plain

画面上部に Writing AsciiDoc works best with soft-wrap enabled. Do you want to enable it by Yes, take me to the Soft Wrap settings! というメッセージが表示されているのでリンクをクリックします。

f:id:ksby:20210103195414p:plain

「Settings」ダイアログが開くので「Soft-wrap these files」をチェックして「OK」ボタンをクリックします。

f:id:ksby:20210103194424p:plain

そうすると画面右側にはみ出ていた文章が折り返されるようになります。https://www.jetbrains.com/help/idea/2020.3/settings-editor-general.html の「Soft Wraps」参照。

f:id:ksby:20210103194644p:plain

また [source, の後で Ctrl+Space を押すと記述可能な言語一覧が表示されます。他にも補完してくれるところがあるのかもしれませんが、現時点で見つけたのはこの１つです。

f:id:ksby:20210103195639p:plain

asciidoctor タスクを実行して index.html を生成する

Gradle Tool Window から asciidoctor タスクをダブルクリックして実行します。BUILD SUCCESSFUL のメッセージが出力されましたが、Java 11 を使っていることに伴う WARNING メッセージも出ていますね。。。

f:id:ksby:20210103200845p:plain

タスクが完了すると build/docs/asciidoc/index.html が生成されます。

f:id:ksby:20210103201315p:plain

build/docs/asciidoc/index.html を開くと以下の画像の HTML が表示されますが、

  • html タグの lang 属性が en になっています。
  • <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> の記述があり、fonts.googleapis.com にアクセスできることが前提になっています。

f:id:ksby:20210103201548p:plain

また IntelliJ IDEA で HTML を開いた時に表示されるブラウザのアイコン一覧から Chrome のアイコンをクリックして表示させてみると、

  • AsciiDoc Plugin の Preview と結構見た目に差異があります。
  • Ruby も Java もシンタックスハイライトが有効になっていません。
  • 一番下に Last updated ... が追加されていました。

f:id:ksby:20210103201858p:plain

asciidoctor タスク実行時に WARNING メッセージが出力されないようにする

gradlew asciidoctor --debug > debug.log 2>&1 コマンドを実行して出力された debug.log を確認したところ（debug.log ファイルを開くと Ideolog plugin のインストールを勧められましたがインストールしない方が見やすく表示されました）、

f:id:ksby:20210105234520p:plain

D:\Java\jdk-11.0.9.101-hotspot\bin\java.exe -Dfile.encoding=windows-31j -Duser.country=JP -Duser.language=ja -Duser.variant -cp C:\Users\root\.gradle\caches\jars-8\28518181ef42d5f97a24177c6fc430c1\asciidoctor-gradle-jvm-3.3.0.jar;C:\Users\root\.gradle\wrapper\dists\gradle-6.7.1-bin\bwlcbys1h7rz3272sye1xwiv6\gradle-6.7.1\lib\groovy-all-1.3-2.5.12.jar;C:\Users\root\.gradle\caches\modules-2\files-2.1\org.asciidoctor\asciidoctorj\2.4.1\37e4d975e2479bd03a348e3d9c77a89fa510f0bb\asciidoctorj-2.4.1.jar;C:\Users\root\.gradle\caches\modules-2\files-2.1\org.jruby\jruby-complete\9.2.13.0\1e6de00e7bea5ff3c9d6086fd9e2610258c051ce\jruby-complete-9.2.13.0.jar;C:\Users\root\.gradle\caches\modules-2\files-2.1\org.asciidoctor\asciidoctorj-api\2.4.1\6cd3abc3bff2d32a7ede570ddb950b42c404465e\asciidoctorj-api-2.4.1.jar;C:\Users\root\.gradle\caches\modules-2\files-2.1\com.beust\jcommander\1.72\6375e521c1e11d6563d4f25a07ce124ccf8cd171\jcommander-1.72.jar;C:\Users\root\.gradle\wrapper\dists\gradle-6.7.1-bin\bwlcbys1h7rz3272sye1xwiv6\gradle-6.7.1\lib\guava-27.1-android.jar org.asciidoctor.gradle.remote.AsciidoctorJavaExec D:\project-springboot\ksbysample-asciidoctor\build\tmp\asciidoctor.javaexec-data

と java.exe でコマンドを実行された直後に WARNING メッセージが出力されていました。

ということは java.exe でコマンドを実行する時に --add-opens=... を指定できれば解決するので、環境変数 JDK_JAVA_OPTIONS に --add-opens=... を設定することで出力されないようにします。

IntelliJ IDEA のメインメニューから「Run」-「Edit Configurations...」を選択し、「Run/Debug Configurations」ダイアログを表示します。

画面左側の「Gradle」の下に ksbysample-asciidoctor [asciidoctor] が出来ているので、選択してから画面右側の「Environment variables」に JDK_JAVA_OPTIONS="--add-opens=java.base/java.lang=ALL-UNNAMED" "--add-opens=java.base/java.util=ALL-UNNAMED" を追加して「OK」ボタンをクリックします。

f:id:ksby:20210105001247p:plain

clean タスク実行 → asciidoctor タスク実行すると NOTE: Picked up JDK_JAVA_OPTIONS: ... というメッセージは出ますが WARNING メッセージは出なくなりました。

f:id:ksby:20210105001735p:plain

html タグの lang 属性を ja にする

document header に :lang: ja を記述すれば html タグの lang 属性が ja になります。

f:id:ksby:20210105005825p:plain

f:id:ksby:20210105005935p:plain

また : の後に Ctrl+Space を押すと AsciiDoc Plugin により候補が表示されました。

f:id:ksby:20210105235705p:plain

シンタックスハイライトを有効にする

シンタックスハイライトを有効にするには document header に :source-highlighter: ... を記述するか、

f:id:ksby:20210105010710p:plain

build.gradle に asciidoctorj { attributes "source-highlighter" : "..." } を記述します。今回は build.gradle の方で設定します。

plugins {
    id "org.asciidoctor.jvm.convert" version "3.3.0"
}

repositories {
    mavenCentral()
}

asciidoctor {
    sourceDir file("src/docs/asciidoc")
    sources {
        include "index.adoc"
    }
}

asciidoctorj {
    attributes "source-highlighter" : "rouge"
}

asciidoctor タスクを実行すると今度はシンタックスハイライトが有効になりました。

f:id:ksby:20210105011221p:plain

source-highlighter に指定可能な文字列は 46.2. Available Source Highlighters に列挙されています。全て試してみましたが、個人的な好みは rouge ですね。

asciidoctor タスクで実行する java.exe のコマンドで -Xverify:none、-XX:TieredStopAtLevel=1 オプションを指定して高速化する

asciidoctor タスクを実行すると 7秒前後かかりますが、

f:id:ksby:20210106001003p:plain

asciidoctor タスク実行時に WARNING メッセージが出力されないようにする で、このタスク内で別途 java.exe を起動していることが分かりました。ということは 開発環境で Web アプリを起動する時には -XX:TieredStopAtLevel=1 オプションを指定する で調べた -Xverify:none と -XX:TieredStopAtLevel=1 オプションを指定すれば早くなる可能性があります。

「Run/Debug Configurations」ダイアログを開いてから ksbysample-asciidoctor [asciidoctor] タスクの「Environment variables」を JDK_JAVA_OPTIONS="--add-opens=java.base/java.lang=ALL-UNNAMED" "--add-opens=java.base/java.util=ALL-UNNAMED" "-Xverify:none" "-XX:TieredStopAtLevel=1" に変更します。

f:id:ksby:20210106001838p:plain

clean タスク実行 → asciidoctor タスク実行を繰り返してみると、だいたい 4秒前後まで実行時間が短縮されました。

f:id:ksby:20210106002133p:plain

履歴

2021/01/06
初版発行。