かんがるーさんの日記

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

Asciidoctor Diagram を使用して AsciiDoc 形式のドキュメントに PlantUML の図を埋め込む

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

概要

記事一覧はこちらです。

Asciidoctor Diagram を使用することで AsciiDoc 形式のドキュメントに PlantUML の図を埋め込めるようなので試してみます。

参照したサイト・書籍

  1. Asciidoctor Diagram
    https://asciidoctor.org/docs/asciidoctor-diagram/

  2. asciidoctor / asciidoctor-diagram
    https://github.com/asciidoctor/asciidoctor-diagram

  3. PlantUML 概要
    https://plantuml.com/ja/

  4. Graphviz - Graph Visualization Software
    https://graphviz.org/

目次

  1. build.gradle に Asciidoctor Diagram の設定を追加する
  2. src/docs/asciidoc/03_diagram ディレクトリを作成する
  3. index.adoc を作成し PlantUML の diagram を記述する
  4. asdiidoctor タスクを実行して PlantUML の図が表示されることを確認する
  5. Asciidoctor Diagram の 2.1.0 では Graphviz をインストールしていなくても画像ファイルが生成できるようになった模様
  6. PlantUML integration Plugin をインストールし、PlantUML のコードを拡張子 .puml の別ファイルに分ける

手順

build.gradle に Asciidoctor Diagram の設定を追加する

Using AsciidoctorJ Diagram を参考に build.gradle を以下のように変更します。

..........

asciidoctorj {
    modules {
        diagram.use()
        diagram.version "2.1.0"
    }
    attributes "source-highlighter" : "rouge"
}

src/docs/asciidoc/03_diagram ディレクトリを作成する

src/docs/asciidoc の下に 03_diagram ディレクトリを作成します。

index.adoc を作成し PlantUML の diagram を記述する

src/docs/asciidoc/03_diagram の下に index.adoc を新規作成し、以下の内容を記述します。PlantUML のコードは https://plantuml.com/ja/ に掲載されていたものをコピーしました。

  • [plantuml, ...] を記述してから .... ～ ..... の間に PlantUML のコードを記述します。
  • [plantuml, ...] の２番目のパラメータに生成する画像ファイル名、３番目のパラメータに生成する画像のタイプを記述します。
  • 各 diagram 毎の生成可能な画像のタイプは Creating a Diagram に記載されています。plantuml は png, svg, txt がサポートされていました。今回は svg を指定します。
= AsciiDoc 形式のドキュメントに PlantUML の図を埋め込む
Doc Writer <doc@example.com>
:lang: ja

== シーケンス図

[plantuml,example-sequence,svg]
....
@startuml
Alice -> Bob: Authentication Request

alt successful case

    Bob -> Alice: Authentication Accepted

else some kind of failure

    Bob -> Alice: Authentication Failure
    group My own label
    Alice -> Log : Log attack start
        loop 1000 times
            Alice -> Bob: DNS Attack
        end
    Alice -> Log : Log attack end
    end

else Another type of failure

   Bob -> Alice: Please repeat

end
@enduml
....

== クラス図

[plantuml,example-class,svg]
....
@startuml

abstract class AbstractList
abstract AbstractCollection
interface List
interface Collection

List <|-- AbstractList
Collection <|-- AbstractCollection

Collection <|- List
AbstractCollection <|- AbstractList
AbstractList <|-- ArrayList

class ArrayList {
  Object[] elementData
  size()
}

enum TimeUnit {
  DAYS
  HOURS
  MINUTES
}

annotation SuppressWarnings

@enduml
....

AsciiDoc Plugin の preview を見ると PlantUML の図が表示されません。エディタ上部に To be able to show diagrams in the preview, download asciidoctorj-diagram or enable Kroki in the settings. というメッセージが表示されていますので Yes, download now! をクリックします。

f:id:ksby:20210123221600p:plain

asciidoctorj-diagram の jar ファイルがダウンロードされて、今度は preview に PlantUML の図が表示されるようになりました。

f:id:ksby:20210123221821p:plain

ただし asciidoctorj-diagram の jar ファイルが 2.1.0 でないようで、クラス図の方は図が表示されませんでした。

f:id:ksby:20210123235029p:plain

asdiidoctor タスクを実行する

asciidoctor タスクを実行すると BUILD SUCCESSFUL が出力されました。

f:id:ksby:20210123214642p:plain

build/docs/asciidoc/03_diagram の下に index.html と画像ファイルが出力されており、

f:id:ksby:20210123222354p:plain:w300

index.html をブラウザで開くと PlantUML の図が表示されました。

f:id:ksby:20210123222529p:plain f:id:ksby:20210123222611p:plain

Asciidoctor Diagram の 2.1.0 では Graphviz をインストールしていなくても画像ファイルが生成できるようになった模様

build.gradle の diagram.version を 2.0.5 にしてから clean タスク実行 → asciidoctor タスク実行を行うと、

.........

asciidoctorj {
    modules {
        diagram.use()
        diagram.version "2.0.5"
    }
    attributes "source-highlighter" : "rouge"
}

build/docs/asciidoc/03_diagram/example-sequence.svg は図が表示されますが、

f:id:ksby:20210123224354p:plain

build/docs/asciidoc/03_diagram/example-class.svg は Dot Executable: null No dot executable found Cannot find Graphviz. のメッセージが表示されて図が生成されません。

f:id:ksby:20210123224518p:plain

このメッセージが表示された場合、Graphviz - Graph Visualization Software から Windows のインストーラーをダウンロードしてインストールすれば図が生成されるのですが、diagram.version を 2.1.0 にすると Graphviz がインストールされていなくてもどちらの図も生成されるようになりました。

PlantUML integration Plugin をインストールし、PlantUML のコードを拡張子 .puml の別ファイルに分ける

AsciiDoc Plugin の preview ではクラス図の方が表示されませんでしたが、IntelliJ IDEA には PlantUML integration Plugin があり、PlantUML のコードを拡張子 .puml のファイルに分けると PlantUML integration Plugin の画面に表示させることができます。PlantUML integration Plugin をインストールしてコードを別ファイルに分けてみます。

IntelliJ IDEA で「Settings」ダイアログを開き、plantuml で検索して PlantUML integration Plugin をインストールします。

f:id:ksby:20210124091538p:plain

インストールすると IntelliJ IDEA の画面右側に「PlantUML」が表示されます。

f:id:ksby:20210124091949p:plain

src/docs/asciidoc/03_diagram の下に example-sequence.puml を新規作成し、index.adoc の [plantuml,example-sequence,svg] .... ～ .... の中のコードをこのファイルに移動します。生成されたシーケンス図が PlantUML integration Plugin の画面に表示されます。

f:id:ksby:20210124092536p:plain

src/docs/asciidoc/03_diagram の下に example-class.puml を新規作成し、index.adoc の [plantuml,example-class,svg] .... ～ .... の中のコードをこのファイルに移動します。生成されたクラス図が PlantUML integration Plugin の画面に表示されます。

f:id:ksby:20210124092756p:plain

index.adoc では example-sequence.puml、example-class.puml を include するよう変更します。

= AsciiDoc 形式のドキュメントに PlantUML の図を埋め込む
Doc Writer <doc@example.com>
:lang: ja

== シーケンス図

[plantuml,example-sequence,svg]
....
include::example-sequence.puml[]
....

== クラス図

[plantuml,example-class,svg]
....
include::example-class.puml[]
....

include directive で別ファイルを取り込んでも AsciiDoc Plugin の preview に PlantUML の図が表示されます。

f:id:ksby:20210124093119p:plain

clean タスク実行 → asciidoctor タスク実行をすると BUILD SUCCESSFUL が表示されて、

f:id:ksby:20210124093359p:plain

build/docs/asciidoc/03_diagram の下にファイル分割前と同じように index.html 等が生成されており（拡張子 .puml のアイコンが PlantUML integration Plugin と同じアイコンになっています）、

f:id:ksby:20210124093706p:plain:w300

index.html をブラウザで開くと PlantUML の図が表示されました。

f:id:ksby:20210124093955p:plain

履歴

2021/01/24
初版発行。

Antora で AsciiDoc 形式のドキュメントが保存されたレポジトリからドキュメントサイトを生成してみる

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

概要

記事一覧はこちらです。

AsciiDoctor は AsciiDoc 形式のドキュメントから HTML ファイル等を作成するためのツールですが、Antora は AsciiDoc 形式のドキュメントが保存されたマルチレポジトリからファイルを取得してドキュメントサイトを生成するためのツールとのこと。TOC を作るだけでなく HTML ファイルを含めてサイト全体を作ってくれるらしい。

AsciiDoctor を使った方がよいのか Antora を使った方がよいのか少し悩みましたが、よく見ると開発している人は同じようです。Antora のページの一番下にどちらも記載されていました。

そもそも Antora の使い方を知らないので、環境を構築してドキュメントサイトを生成してみることにします。

参照したサイト・書籍

  1. Antora
    https://antora.org/

  2. Antora Documentation
    https://docs.antora.org/antora/2.3/

  3. Announcing Antora
    https://discuss.asciidoctor.org/Announcing-Antora-td6049.html

  4. Converting existing AsciiDoc into an Antora project
    https://blog.anoff.io/2019-02-15-antora-first-steps/

目次

  1. Antora で生成されたサイトの画面構成のメモ書き
  2. サンプル作成の方針をまとめる
  3. ksbysample-antora レポジトリ（AsciiDoc 形式のドキュメントを置くレポジトリ）を作成する
  4. v1.0 ブランチを作成し ksbysample-asciidoctor レポジトリから 01_simple ディレクトリの adoc ファイルをコピーする
    1. main ブランチから v1.0 ブランチを作成する
    2. ksbysample-asciidoctor レポジトリから 01_simple ディレクトリの adoc ファイルをコピーする
    3. nav.adoc を作成する
    4. antora.yml を作成する
    5. v1.0 ブランチを main ブランチへマージする
  5. v2.0 ブランチを作成し ksbysample-asciidoctor レポジトリから 02_include ディレクトリの adoc ファイルをコピーする
    1. main ブランチから v2.0 ブランチを作成する
    2. ksbysample-asciidoctor レポジトリから 02_include ディレクトリの adoc ファイルをコピーする
    3. nav.adoc を変更する
    4. antora.yml を変更する
    5. v2.0 ブランチを main ブランチへマージする
  6. ksbysample-antora-playbook レポジトリ（Antora をインストールしてドキュメントサイトを生成するためのレポジトリ）を作成する
  7. antora-playbook.yml を作成する
  8. npm install --save-dev @antora/cli @antora/site-generator-default を実行する
  9. npx antora --fetch antora-playbook.yml を実行してドキュメントサイトを生成する

手順

Antora で生成されたサイトの画面構成のメモ書き

Antora で生成された画面とドキュメントが保存されたレポジトリ及びレポジトリ内のファイルの関係が分からなかったので、調べた内容のメモ書きです。

f:id:ksby:20210116191422p:plain

  • 復数のレポジトリからドキュメントを収集して HTML ファイルを生成することができ、収集元のレポジトリが ② に表示されます。レポジトリから復数バージョン取得した時には以下のように表示される模様。表示させたいドキュメント（バージョン番号が表示されている部分）をクリックすると、①③④の表示が選択されたドキュメントに切り替わります。

    f:id:ksby:20210116193846p:plain

  • ①に表示されるのは Navigation と呼ばれており（https://docs.antora.org/antora/2.3/navigation/ 参照）、各レポジトリ内で nav.adoc のようなファイルに記述し（自動生成されるのではなく自分で記述します）、各レポジトリの antora.yml の nav: に Navigation の adoc ファイルを列挙します。

  • ④の部分は普通に adoc ファイルを作成して AsciiDoc 形式で記述します。
  • ③の部分（④に表示されるドキュメントの TOC）は Antora で HTML ファイルを生成する時に自動生成されます。
  • ⑤の部分は antora-playbook.yml の ui.bundle.url で指定します。ただし「Search the docs」という入力フィールドがありますが、これは DocSearch というサービスによるもので Antora で生成できるものではありませんでした。

サンプル作成の方針をまとめる

  • １つのレポジトリ内に antora.yml、antora-playbook.yml を配置してドキュメントサイトを生成することもできるようですが、Antora は復数のレポジトリに作成されている AsciiDoc 形式のドキュメントを収集してドキュメントサイトを生成するためのツールなので、AsciiDoc 形式のドキュメントを置くレポジトリを１つ、Antora をインストールしてドキュメントサイトを生成するためのレポジトリを１つ作成することにします。
    • ksbysample-antora（AsciiDoc 形式のドキュメントを置くレポジトリ）
    • ksbysample-antora-playbook（Antora をインストールしてドキュメントサイトを生成するためのレポジトリ）
  • ksbysample-antora レポジトリに置く AsciiDoc 形式のドキュメントは ksbysample-asciidoctor レポジトリからコピーします。
  • ksbysample-antora レポジトリには v1.0 ブランチ（01_simple ディレクトリの adoc ファイルだけ格納する）、v2.0 ブランチ（02_include ディレクトリの adoc ファイルも格納する）の２つのブランチを作成し、ドキュメントサイト生成時にこの２つのブランチを指定します。

ksbysample-antora レポジトリ（AsciiDoc 形式のドキュメントを置くレポジトリ）を作成する

  1. Github で ksbysample-antora レポジトリ を作成します。
  2. D:\project-springboot\ksbysample-antora に clone します。
  3. プロジェクトのルートディレクトリの下に modules/ROOT/pages ディレクトリを作成します。ディレクトリ構成は Standard File and Directory Set 参照。
  4. .gitignore に以下の内容を記述します。
# Intellij project files
*.iml
*.ipr
*.iws
.idea/

v1.0 ブランチを作成し ksbysample-asciidoctor レポジトリから 01_simple ディレクトリの adoc ファイルをコピーする

main ブランチから v1.0 ブランチを作成する

main ブランチから v1.0 ブランチを作成します。

ksbysample-asciidoctor レポジトリから 01_simple ディレクトリの adoc ファイルをコピーする

ksbysample-asciidoctor レポジトリの src/docs/asciidoc ディレクトリの下の 01_simple/index.adoc をコピーし、modules/ROOT/pages の下にペーストします。

nav.adoc を作成する

modules/ROOT の下に nav.adoc を新規作成し、以下の内容を記述します。Navigation Files and Lists 参照。

* xref:ROOT:01_simple/index.adoc[Hello, AsciiDoc!]

antora.yml を作成する

プロジェクトのルートディレクトリ直下に antora.yml を新規作成し、以下の内容を記述します。What’s antora.yml? 参照。

name: ksbysample-antora
title: ksbysample-antora
version: v1.0
start_page: ROOT:01_simple/index.adoc
nav:
  - modules/ROOT/nav.adoc

v1.0 ブランチを main ブランチへマージする

v1.0 ブランチを main ブランチへマージします。ここまでで以下のディレクトリ構成になります。

f:id:ksby:20210120005550p:plain:w300

v2.0 ブランチを作成し ksbysample-asciidoctor レポジトリから 02_include ディレクトリの adoc ファイルをコピーする

main ブランチから v2.0 ブランチを作成する

main ブランチから v2.0 ブランチを作成します。

ksbysample-asciidoctor レポジトリから 02_include ディレクトリの adoc ファイルをコピーする

ksbysample-asciidoctor レポジトリの src/docs/asciidoc ディレクトリの下の 02_include ディレクトリ をコピーし、modules/ROOT/pages の下にペーストします。index.adoc は使用しないので削除します。

次に Hierarchy and reserved names に従い、modules/ROOT/pages/02_include の下の images ディレクトリを modules/ROOT の下へ移動します。

画像のパスが変わるので modules/ROOT/pages/02_include/01.adoc を以下のように変更します。

.....

Shift キーを２回押してダイアログを表示した後、「Git」タブを選択してから `redis`（commit message にこの文字列が入力されているものがあります）と入力してみましたが、何も表示されず。。。

image::01-01.png[,420,423]

ダイアログ右上の「Filter」ボタンをクリックすると「Commit by hash」しかチェックされていませんでした。

image::01-02.png[,558,158]

「All」ボタンをクリックして全てチェックすると commit message も検索してヒットしたものが表示されるようになりました。

image::images/01-03.png[,562,179]
  • images:: の後の images/ を取り除きます。
    • image::images/01-01.png[,420,423] → image::01-01.png[,420,423]
    • image::images/01-02.png[,558,158] → image::01-02.png[,558,158]
    • image::images/01-03.png[,562,179] → image::01-03.png[,562,179]

変更すると AsciiDoc Plugin の preview に画像が表示されるようになりました。Antora のディレクトリ構成にしておくと自動で判別して表示くれるようです。

f:id:ksby:20210120204440p:plain

またエディタ上部に表示されている It seems you are editing a document that is part of an Antora module. Do you want to learn more how this plugin can support you? のメッセージの Yes, tell me more! のリンクをクリックすると AsciiDoc Plugin の Antora に関するドキュメント にジャンプします（このページも Antora で作成されていました）。

nav.adoc を変更する

modules/ROOT/nav.adoc に .include directive で章毎にファイルを分けてみる 以降の記述を追加します。

* xref:ROOT:01_simple/index.adoc[Hello, AsciiDoc!]

.include directive で章毎にファイルを分けてみる
* xref:ROOT:02_include/01.adoc[IntelliJ IDEA 2020.3 新機能メモ書き]
* xref:ROOT:02_include/02.adoc[Asciidoctor+Gradle の環境で AsciiDoc 形式のドキュメントから HTML ファイルを生成してみる]

antora.yml を変更する

antora.yml を以下のように変更します（version を変更しただけです）。

name: ksbysample-antora
title: ksbysample-antora
version: v2.0
start_page: ROOT:01_simple/index.adoc
nav:
  - modules/ROOT/nav.adoc

v2.0 ブランチを main ブランチへマージする

v2.0 ブランチを main ブランチへマージします。ここまでで以下のディレクトリ構成になります。

f:id:ksby:20210121001309p:plain:w300

Git のレポジトリは以下のようになっています。

f:id:ksby:20210121001411p:plain

ksbysample-antora-playbook レポジトリ（Antora をインストールしてドキュメントサイトを生成するためのレポジトリ）を作成する

  1. Github で ksbysample-antora-playbook レポジトリ を作成します。
  2. D:\project-springboot\ksbysample-antora-playbook に clone します。
  3. .gitignore に以下の内容を記述します。
# Intellij project files
*.iml
*.ipr
*.iws
.idea/

# Node.js, npm
node_modules/
npm-debug.log

# Antora
build/

antora-playbook.yml を作成する

プロジェクトのルートディレクトリ直下に antora-playbook.yml を新規作成し、以下の内容を記述します。Set Up a Playbook を参考に記述しており、ui.bundle はそのままコピーしています。

site:
  title: ksbysample-document-site
  start_page: ksbysample-antora::01_simple/index.adoc
content:
  sources:
    - url: https://github.com/ksby/ksbysample-antora.git
      branches: [v2.0, v1.0]
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

npm install --save-dev @antora/cli @antora/site-generator-default を実行する

Install Antora を見て、以下のコマンドを実行します。ドキュメントには global にインストールするよう記述されていますが、今回はプロジェクト内にインストールします。

  • npm init -y
  • npm install --save-dev @antora/cli @antora/site-generator-default

f:id:ksby:20210121003117p:plain f:id:ksby:20210121003257p:plain

npx antora --fetch antora-playbook.yml を実行してドキュメントサイトを生成する

npx antora --fetch antora-playbook.yml を実行します。

f:id:ksby:20210121003503p:plain

ドキュメントサイトのファイルが build ディレクトリの下に生成されます。以下のディレクトリ構成になりました。

f:id:ksby:20210121004253p:plain:w300

build/site/index.html を開くと v2.0 のドキュメントが表示されます。日本語の表示はそのままでも十分見やすい印象です。

f:id:ksby:20210121005942p:plain f:id:ksby:20210121010046p:plain

左下のレポジトリ一覧を表示させると ksbysample-antora に v2.0、v1.0 が表示されており、

f:id:ksby:20210121010150p:plain

v1.0 をクリックすると 01_simple ディレクトリのドキュメントだけが表示されました。

f:id:ksby:20210121010233p:plain

AsciiDoctor もいいけど Antora もいいですね。Web で調べていた時には少し使いづらい、Sphinx の方がよい（Doma 2 のドキュメントが Sphinx ですね）、というコメントも見かけましたが個人的には好みです。

あと Spring の Documentation の左側の TOC（自動的に開閉するタイプ）があまり好みではないので、Antora で作って、かつ DocSearch を入れてくれないかな。。。と、今回調べていてちょっと思いました。

履歴

2021/01/21
初版発行。

TOC（Table of Contents）を自動生成して表示させる

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

概要

記事一覧はこちらです。

AsciiDoc で作成されたドキュメントを見ると右か左に TOC（Table of Contents）が表示されています。Spring Boot や JUnit 5 のドキュメントだと下にスクロールさせると TOC が自動的に展開されて現在見ている section が分かるようになっています。TOC（Table of Contents）があるとドキュメントが見やすいので、同じように表示させてみます。

個人的には以下のドキュメントの TOC（Table of Contents）の方が好みなので、この TOC の実現方法も調べてみます。

参照したサイト・書籍

  1. Automatic Table of Contents
    https://docs.asciidoctor.org/asciidoc/latest/toc/

  2. unit-team / junit5/documentation/src/docs/asciidoc/
    https://github.com/junit-team/junit5/tree/main/documentation/src/docs/asciidoc

  3. Add expandable/collapsable TOC
    https://github.com/asciidoctor/asciidoctor/issues/699

  4. Tocbot
    https://tscanlin.github.io/tocbot/

  5. copyfiles
    https://www.npmjs.com/package/copyfiles

  6. Asciidoctor Gradle Examples
    https://asciidoctor.github.io/asciidoctor-gradle-examples/

    • 今回の記事とは直接関係がありませんが、見つけたのでメモとして書いておきます。

目次

  1. document header に :toc: left、:toclevels: 4 を追加して TOC を表示させる
  2. Tocbot を導入して TOC が自動展開される＋参照中の section が分かるようにする
    1. npm init -y を実行する
    2. npm install --save tocbot を実行する
    3. src/docs/asciidoc/js ディレクトリを作成して Tocbot の js ファイルをコピーする
    4. asciidoctor タスク実行時に js ファイルが build ディレクトリにコピーされるようにする
    5. docinfo.html、docinfo-footer.html に Tocbot を使用するために必要なコードを記述する
    6. asciidoctor タスクを実行して動作確認する
  3. AsciiDoc Language Documentation、Asciidoctor Documentation と同じ TOC の実現は次回へ

手順

document header に :toc: left、:toclevels: 4 を追加して TOC を表示させる

Spring Boot Reference Documentation の adoc ファイルを参考に document header を追加する で追加しなかった :toc: left、:toclevels: 4 を document header に追加して TOC を自動生成させてみます。

src/docs/asciidoc/02_include/index.adoc を以下のように変更します。

= include directive で章毎にファイルを分けてみる
:lang: ja
:doctype: book
:idprefix:
:idseparator: -
:toc: left
:toclevels: 4
:tabsize: 4
:sectanchors:
:sectnums:
:icons: font
:hide-uri-scheme:
:docinfo: shared,private
:docinfodir: ../../docinfo

include::01.adoc[leveloffset=+1]
include::02.adoc[leveloffset=+1]
  • 以下の２行を追加します。
    • :toc: left
    • :toclevels: 4

asciidoctor タスクを実行して html を表示させてみると左側に TOC が表示されましたが、TOC は展開済みの状態で、下にスクロールした時に TOC が自動的に展開されて現在見ている section が分かるようにはなっていませんでした。:toc: を追加するだけでは実現できないようです。

f:id:ksby:20210113232953p:plain

Tocbot を導入して TOC が自動展開される＋参照中の section が分かるようにする

TOC を自動的に展開して現在見ている section が分かるようにする方法を調べたところ、JUnit 5 のドキュメントのソース https://github.com/junit-team/junit5/tree/main/documentation/src/docs/asciidoc で Tocbot を使って実現していることが分かりました。

asciidoctor の GitHub にも Add expandable/collapsable TOC の Issue がありました。

同じようにすれば実現できそうです。

npm init -y を実行する

Tocbot のファイルは npm でダウンロードするので、まずは npm init -y を実行します（Node.js、npm のインストールは以下の記事参照）。

f:id:ksby:20210114093003p:plain

npm install --save tocbot を実行する

npm install --save tocbot を実行して Tocbot のファイルをダウンロードします。

f:id:ksby:20210114093741p:plain

node_modules ディレクトリが作成されたので .gitignore に無視するよう設定を追加します。

# Gradle
.gradle/
build/

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

# Node.js, npm
node_modules/
npm-debug.log

src/docs/asciidoc/js ディレクトリを作成して Tocbot の js ファイルをコピーする

npm scripts でファイルをコピーするのに以前は cpx をインストールして使っていましたが、最近使われているモジュールを調べてみるとダウンロード数が多いのは ncp らしいです。

copy vs copyfiles vs cpx vs ncp vs npm-build-tools というサイトを見つけました。ncp は最後のリリースは 6年前ですが圧倒的にダウンロード数が多く、次の copyfiles は最後のリリースが２ヶ月前ですが ncp よりダウンロード数は少ない模様。

今回は copyfiles をインストールして使うことにします。また rimraf、npm-run-all もインストールしたいので、以下のコマンドを実行します。

  • npm install --save-dev copyfiles
  • npm install --save-dev rimraf
  • npm install --save-dev npm-run-all

f:id:ksby:20210114205734p:plain

package.json に postinstall と copy:tocbot の npm scripts を追加してから、

  ..........
  "scripts": {
    "postinstall": "run-s copy:tocbot",
    "copy:tocbot": "copyfiles -f node_modules/tocbot/dist/*.js src/docs/asciidoc/js"
  },
  ..........

npm ci コマンドを実行すると、

f:id:ksby:20210114211240p:plain

src/docs/asciidoc/js ディレクトリが作成されて、その下に tocbot.js、tocbot.min.js がコピーされます。

f:id:ksby:20210114211405p:plain:w300

asciidoctor タスク実行時に js ファイルが build ディレクトリにコピーされるようにする

build.gradle を以下のように変更します。

..........

asciidoctor {
    sourceDir file("src/docs/asciidoc")
    baseDirFollowsSourceFile()
    sources {
        include "**/index.adoc"
    }
    resources {
        from("${sourceDir}") {
            include "**/*.png", 
                    "**/*.js"
        }
    }
}

..........
  • asciidoctor block の resources の中に "**/*.js" を追加します。

docinfo.html、docinfo-footer.html に Tocbot を使用するために必要なコードを記述する

Add expandable/collapsable TOC に docinfo.html、docinfo-footer.html に記述するサンプルがありますので、それを流用して記述します（ほとんどコピーですが流用元の URL の追加と Tocbot の最新版 4.12.1 を使うための設定の追加をしています）。

まずは docinfo.html から。

<style>
..........

/* Source: https://github.com/asciidoctor/asciidoctor/issues/699#issuecomment-321066006 */
#tocbot a.toc-link.node-name--H1{ font-style: italic }
@media screen{
    #tocbot > ul.toc-list{ margin-bottom: 0.5em; margin-left: 0.125em }
    #tocbot ul.sectlevel0, #tocbot a.toc-link.node-name--H1 + ul{
        padding-left: 0 }
    #tocbot a.toc-link{ height:100% }
    .is-collapsible{ max-height:3000px; overflow:hidden; }
    .is-collapsed{ max-height:0 }
    .is-active-link{ font-weight:700 }
}
@media print{
    #tocbot a.toc-link.node-name--H4{ display:none }
}
</style>

次に docinfo-footer.html。ファイル自体がないので src/docs/docinfo ディレクトリの下に新規作成してから以下の内容を記述します。こちらは Ctrl+Alt+L でフォーマットした後、先頭のコードを <script src="/assets/js/tocbot.js"></script> → <script src="../js/tocbot.min.js"></script> へ、tocbot のバージョン番号を 3.0.2 → 4.12.1 へ変更しています。

<!--Source: https://github.com/asciidoctor/asciidoctor/issues/699#issuecomment-321066006-->
<script src="../js/tocbot.min.js"></script>
<script>
  /* Tocbot dynamic TOC, works with tocbot 4.12.1 */
  var oldtoc = document.getElementById('toctitle').nextElementSibling;
  var newtoc = document.createElement('div');
  newtoc.setAttribute('id', 'tocbot');
  newtoc.setAttribute('class', 'js-toc');
  oldtoc.parentNode.replaceChild(newtoc, oldtoc);
  tocbot.init({
    contentSelector: '#content',
    headingSelector: 'h1, h2, h3, h4',
    smoothScroll: false
  });
  var handleTocOnResize = function () {
    var width = window.innerWidth
      || document.documentElement.clientWidth
      || document.body.clientWidth;
    if (width < 768) {
      tocbot.refresh({
        contentSelector: '#content',
        headingSelector: 'h1, h2, h3, h4',
        collapseDepth: 6,
        activeLinkClass: 'ignoreactive',
        throttleTimeout: 1000,
        smoothScroll: false
      });
    } else {
      tocbot.refresh({
        contentSelector: '#content',
        headingSelector: 'h1, h2, h3, h4',
        smoothScroll: false
      });
    }
  };
  window.addEventListener('resize', handleTocOnResize);
  handleTocOnResize();
</script>

asciidoctor タスクを実行して動作確認する

asciidoctor タスクを実行すると BUILD SUCCESSFUL のメッセージが出力されて、

f:id:ksby:20210115082654p:plain

build/docs/asciidoc/js が作成されて、その下に tocbot.js がコピーされており、

f:id:ksby:20210115082842p:plain

index.html を開くと左側に TOC が表示されて、下にスクロールすると TOC が自動的に展開されて現在見ている section が分かるようになりました。

f:id:ksby:20210115084226g:plain

実現できた！と思ったのですが、よく見ると一番上位の階層になぜか番号が余計に付いています。。。

f:id:ksby:20210115084505p:plain

http://tscanlin.github.io/tocbot/ の「API」-「Options」を見ると orderedList という項目があり orderedList can be set to false to generate unordered lists (ul) instead of ordered lists (ol) との記述がありました。おそらくこれを false に設定すれば番号は付かなくなるはず。

src/docs/docinfo/docinfo-footer.html を以下のように変更します。

<!--Source: https://github.com/asciidoctor/asciidoctor/issues/699#issuecomment-321066006-->
<script src="../js/tocbot.min.js"></script>
<script>
  /* Tocbot dynamic TOC, works with tocbot 4.12.1 */
  var oldtoc = document.getElementById('toctitle').nextElementSibling;
  var newtoc = document.createElement('div');
  newtoc.setAttribute('id', 'tocbot');
  newtoc.setAttribute('class', 'js-toc');
  oldtoc.parentNode.replaceChild(newtoc, oldtoc);
  tocbot.init({
    contentSelector: '#content',
    headingSelector: 'h1, h2, h3, h4',
    smoothScroll: false
  });
  var handleTocOnResize = function () {
    var width = window.innerWidth
      || document.documentElement.clientWidth
      || document.body.clientWidth;
    if (width < 768) {
      tocbot.refresh({
        contentSelector: '#content',
        headingSelector: 'h1, h2, h3, h4',
        collapseDepth: 6,
        activeLinkClass: 'ignoreactive',
        throttleTimeout: 1000,
        smoothScroll: false,
        orderedList: false
      });
    } else {
      tocbot.refresh({
        contentSelector: '#content',
        headingSelector: 'h1, h2, h3, h4',
        smoothScroll: false,
        orderedList: false
      });
    }
  };
  window.addEventListener('resize', handleTocOnResize);
  handleTocOnResize();
</script>
  • tocbot.refresh({ ... }); を呼び出しているところ（２ヶ所）に orderedList: false を追加しました。

asciidoctor タスクを実行して index.html を開くと、今度は番号が付いていませんでした。

f:id:ksby:20210115091424p:plain

AsciiDoc Language Documentation、Asciidoctor Documentation と同じ TOC の実現は次回へ

AsciiDoc Language Documentation のソース https://github.com/asciidoctor/asciidoc-docs の記述を見るとと The documentation site is built using Antora. の記述があり、Antora で構築されているとのこと。

Antora で検索すると以下のサイトが見つかりました。

今回はここで区切って Antora を使用するのは次回にします。

履歴

2021/01/16
初版発行。

include directive で adoc ファイルを分ける時に AsciiDoc Plugin の preview が表示されるようにする

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

概要

記事一覧はこちらです。

前回の include directive で章毎に adoc ファイルを分けてみる で、adoc ファイルを include した時に AsciiDoc Plugin の preview にイメージが表示されず、かつ index.adoc 内の記述に赤波下線が表示されていたので、それらを解消します。

参照したサイト・書籍

  1. Include directives and base directory
    https://asciidoctor.github.io/asciidoctor-gradle-plugin/master/user-guide/#_include_directives_and_base_directory

目次

  1. build.gradle に baseDirFollowsSourceFile() を追加する
  2. src/docs/asciidoc/02_include/index.adoc を変更する
  3. asciidoctor タスクを実行して結果を確認する

手順

build.gradle に baseDirFollowsSourceFile() を追加する

Asciidoctor Gradle Plugin Suite の Include directives and base directory を見ると include directive は baseDir に設定されたディレクトリを基準にファイルの位置を判断する模様。

この section には baseDir... で始まるメソッドが４つ記載されていますが、index.adoc のあるディレクトリが baseDir になると AsciiDoc Plugin の preview も表示されるようになるので baseDirFollowsSourceFile() を使用することにします。

build.gradle の asciidoctor block に baseDirFollowsSourceFile() を追加します。

..........

asciidoctor {
    sourceDir file("src/docs/asciidoc")
    baseDirFollowsSourceFile()
    sources {
        include "**/index.adoc"
    }
    resources {
        from("${sourceDir}") {
            include "**/*.png"
        }
    }
}

..........

src/docs/asciidoc/02_include/index.adoc を変更する

src/docs/asciidoc/02_include/index.adoc を以下のように変更します。

= include directive で章毎にファイルを分けてみる
:lang: ja
:doctype: book
:idprefix:
:idseparator: -
:tabsize: 4
:sectanchors:
:sectnums:
:icons: font
:hide-uri-scheme:
:docinfo: shared,private
:docinfodir: ../../docinfo

include::01.adoc[leveloffset=+1]
include::02.adoc[leveloffset=+1]
  • docinfodir の Path も baseDir のディレクトリを基準に判断されるので、:docinfodir: src/docs/docinfo → :docinfodir: ../../docinfo に変更します。
  • include directive で指定している Path から src/docs/asciidoc/02_include/ を削除してファイル名だけにします。

index.adoc に赤波下線が表示されなくなり、AsciiDoc Plugin の preview 上に include した adoc ファイルの内容が表示されるようになりました。

f:id:ksby:20210113191203p:plain

asciidoctor タスクを実行して結果を確認する

asciidoctor タスクを実行すると特にエラーメッセージは出ずに BUILD SUCCESSFUL が出力されて、

f:id:ksby:20210113191908p:plain

build/docs/asciidoc/02_include/index.html を表示すると include したファイルの内容が表示されており、docinfo.html の css も適用されて本文のフォントがゴシック体になっていました。

f:id:ksby:20210113192117p:plain

adoc ファイルを同じディレクトリ内に配置するならばこの方法で良さそうです。

履歴

2021/01/13
初版発行。

include directive で章毎に adoc ファイルを分けてみる

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

概要

記事一覧はこちらです。

Spring Boot Reference Documentation の AsciiDoc 形式のドキュメントのソースが https://github.com/spring-projects/spring-boot/tree/master/spring-boot-project/spring-boot-docs/src/docs/asciidoc にありますが、index.singleadoc の中を見てみると各章は個別のファイルに記述してそれを include directive で取り込んでいました。

同じことを試してみます。

参照したサイト・書籍

目次

  1. src/docs/asciidoc/index.adoc を src/docs/asciidoc/01_simple の下に移動する
  2. src/docs/asciidoc の下に 02_include ディレクトリを作成する
  3. 01.adoc を作成する
  4. 02.adoc を作成する
  5. index.adoc を作成して 01.adoc、02.adoc を include する
  6. build.gradle を変更し asciidoctor タスクを実行する
  7. Spring Boot Reference Documentation の adoc ファイルを参考に document header を追加する
  8. dockinfo.html に css を記述して出力された html の見た目を変更する

手順

src/docs/asciidoc/index.adoc を src/docs/asciidoc/01_simple の下に移動する

今後のサンプルは src/docs/asciidoc ディレクトリの下に 01、02、..... と連番の付いたディレクトリを作成してその下に作成するようにしたいので、src/docs/asciidoc の下に 01_simple ディレクトリを作成して src/docs/asciidoc/index.adoc をその下に移動します。

build.gradle を以下のように変更します。

..........

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

..........
  • asciidoctor block で include "index.adoc" → include "01_simple/index.adoc" に変更します。

src/docs/asciidoc の下に 02_include ディレクトリを作成する

src/docs/asciidoc の下に 02_include ディレクトリを作成します。

01.adoc を作成する

include directive で取り込むファイルとして 01.adoc、02.adoc の２つのファイルを作成します。

まずは 01.adoc から。IntelliJ IDEA 2020.3 新機能メモ書き の記事の一部をコピーして作成します。画像ファイルを３つ src/docs/asciidoc/02_include/images の下に 01-01.png、01-02.png、01-03.png のファイル名で配置します。

[[idea-20203-whatsnew]]
= IntelliJ IDEA 2020.3 新機能メモ書き

[[idea-20203-whatsnew-overview]]
== 概要

IntelliJ IDEA 2020.3 にバージョンアップしたので新機能を確認した時のメモ書きです。

[[idea-20203-whatsnew-reference]]
== 参照したサイト・書籍

* What’s New in IntelliJ IDEA 2020.3 +
https://www.jetbrains.com/idea/whatsnew/#whats-new-20203

[[idea-20203-whatsnew-item]]
== 手順

[[idea-20203-whatsnew-item-search-everywhere-updates]]
=== Search Everywhere updates

Search Everywhere dialog で `commit hashes and messages, tags, and branches` が検索できるようになりました。

Shift キーを２回押してダイアログを表示した後、「Git」タブを選択してから `redis`（commit message にこの文字列が入力されているものがあります）と入力してみましたが、何も表示されず。。。

image::images/01-01.png[,420,423]

ダイアログ右上の「Filter」ボタンをクリックすると「Commit by hash」しかチェックされていませんでした。

image::images/01-02.png[,558,158]

「All」ボタンをクリックして全てチェックすると commit message も検索してヒットしたものが表示されるようになりました。

image::images/01-03.png[,562,179]

02.adoc を作成する

次は 02.adoc。Asciidoctor+Gradle の環境で AsciiDoc 形式のドキュメントから HTML ファイルを生成してみる の記事の一部をコピーして作成します。

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

[[asciidoctor-gradle-makehtml-overview]]
== 概要

https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/[Spring Boot Reference Documentation] が AsciiDoc 形式のドキュメントで記述されていることは知っていたのですが、これまで AsciiDoc 形式で記述したことがありませんでした。 https://junit.org/junit5/docs/current/user-guide/[JUnit 5 のドキュメント] やこの前 https://ksby.hatenablog.com/entry/2020/12/26/233231[Spring Boot 2.2.x の Web アプリを 2.3.x へバージョンアップする ( 番外編 )( IntelliJ IDEA の docToolchain/diagrams.net-intellij-plugin を追加する )] でインストールした https://drawio-intellij-plugin.netlify.app/[diagrams.net-intellij-plugin のドキュメント] も AsciiDoc で記述されており、興味が湧いたので使い方を調べてみます。

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

[[asciidoctor-gradle-makehtml-item]]
== 手順

[[asciidoctor-gradle-makehtml-item-makeproject]]
=== ksbysample-asciidoctor プロジェクトを作成する

. Github で ksbysample-asciidoctor レポジトリ を作成します。
. D:\project-springboot\ksbysample-asciidoctor に clone します。

[[asciidoctor-gradle-makehtml-item-write-buildgradle]]
=== build.gradle を記述する

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

[source,groovy]
----
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 の下に出力してくれるようなので省きました。

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

index.adoc を作成して 01.adoc、02.adoc を include する

index.adoc を作成します。

= include directive で章毎にファイルを分けてみる
:lang: ja

include::src/docs/asciidoc/02_include/01.adoc[leveloffset=+1]
include::src/docs/asciidoc/02_include/02.adoc[leveloffset=+1]

include するファイルのパスは project のルートディレクトリからのパスを指定すれば読み込んでくれるのですが、この記述の仕方だと赤波下線が表示されて、かつ preview に 01.adoc、02.adoc の内容が表示されません。。。

f:id:ksby:20210110233552p:plain

build.gradle を変更し asciidoctor タスクを実行する

build.gradle を以下のように変更します。

..........

asciidoctor {
    sourceDir file("src/docs/asciidoc")
    sources {
        include "**/index.adoc"
    }
    resources {
        from("${sourceDir}") {
            include "**/*.png"
        }
    }
}

..........
  • asciidoctor block の以下の点を変更します。
    • sources block の include を "01_simple/index.adoc" → "**/index.adoc" に変更します。
    • resources { ... } を追加して、asciidoctor タスク実行時に画像ファイルが build ディレクトリにコピーされるようにします。

asciidoctor タスクを実行すると無事 BUILD SUCCESSFUL が出力されました。

f:id:ksby:20210110233311p:plain

ディレクトリ構成は以下のようになり、

f:id:ksby:20210110234456p:plain:w300

build/docs/asciidoc/02_include/index.html をブラウザで開くと以下の画像のように表示されました。

f:id:ksby:20210111213351p:plain

Spring Boot Reference Documentation の adoc ファイルを参考に document header を追加する

https://github.com/spring-projects/spring-boot/blob/master/spring-boot-project/spring-boot-docs/src/docs/asciidoc/attributes.adoc のファイルを参考にして document header をいくつか追加します。

index.adoc は以下のようになります。

= include directive で章毎にファイルを分けてみる
:lang: ja
:doctype: book
:idprefix:
:idseparator: -
:tabsize: 4
:sectanchors:
:sectnums:
:icons: font
:hide-uri-scheme:
:docinfo: shared,private

include::src/docs/asciidoc/02_include/01.adoc[leveloffset=+1]
include::src/docs/asciidoc/02_include/02.adoc[leveloffset=+1]

dockinfo.html に css を記述して出力された html の見た目を変更する

build.gradle を変更し asciidoctor タスクを実行する で生成した html ですが、default の css だと個人的には以下の点が好みではありませんでした。

  • 各章の文字の色が赤だが、個人的には黒のままの方が好み。
  • 通常の文章（p タグで囲まれている模様）のフォントが明朝体だが、ゴシック体の方が好み。
  • 全体的に余白はもう少しだけ狭めた方が好み。
  • ソースコードのフォントはもう少し小さい方が好み。

docinfo.html に css を記述すれば生成した html に適用されるようなので、src/docs/docinfo ディレクトリを作成した後、その下に docinfo.html を新規作成して以下の内容を記述します。

<style>
body {
    font-family: -apple-system, "BlinkMacSystemFont", "Helvetica Neue", Helvetica, "Arial", "ヒラギノ角ゴ ProN W3", "Hiragino Kaku Gothic ProN", "メイリオ", Meiryo, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
}
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 {
    font-family: inherit;
    color: inherit;
}
p {
    font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji;
    font-size: 16px;
    line-height: 1.5;
}
pre code, pre pre {
    font-size: 14px;
}
</style>
  • body { ... } を追加し、font-family を設定します。font-family の設定は Honoka - 日本語も美しく表示できるBootstrapテーマ のものをコピーしました。
  • h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: inherit; color: inherit; } を設定して章のフォントは body { ... } に設定したものを使用し、文字色は黒になるようにします。
  • p { ... } を追加し、font-family、font-size、line-height を設定します。GitHub の .markdown-body の設定からコピーしました。
  • pre code, pre pre { font-size: 14px; } を追加し、ソースコードのフォントサイズを少し小さくします。

index.adoc に docinfodir の document header を追加します。

= include directive で章毎にファイルを分けてみる
..........
:docinfo: shared,private
:docinfodir: src/docs/docinfo

asciidoctor タスクを実行すると変更前は以下のように表示されていましたが、

f:id:ksby:20210111221706p:plain

変更後は以下のようになります。

f:id:ksby:20210111221759p:plain

貼り付けた画面キャプチャを見ると明朝体の方が見やすそうですが、ブラウザで見ると下のゴシック体の方が個人的には見やすいですね。

履歴

2021/01/13
初版発行。

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
初版発行。

AsciiDoc＆Asciidoctor＆Antora 覚書（大目次）

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

GitHub は
https://github.com/ksby/ksbysample-asciidoctor
https://github.com/ksby/ksbysample-antora
https://github.com/ksby/ksbysample-antora-playbook

  1. Asciidoctor+Gradle の環境で AsciiDoc 形式のドキュメントから HTML ファイルを生成してみる
  2. include directive で章毎に adoc ファイルを分けてみる
  3. include directive で adoc ファイルを分ける時に AsciiDoc Plugin の preview が表示されるようにする
  4. TOC（Table of Contents）を自動生成して表示させる
  5. Antora で AsciiDoc 形式のドキュメントが保存されたレポジトリからドキュメントサイトを生成してみる
  6. Asciidoctor Diagram を使用して AsciiDoc 形式のドキュメントに PlantUML の図を埋め込む
  7. PlantUML の図を生成するモジュールを Asciidoctor Diagram → Kroki に変更する
  8. PlantUML 以外の diagram を AsciiDoc のドキュメントに埋め込んで見る（bpmn、bytefield 編）
  9. PlantUML 以外の diagram を AsciiDoc のドキュメントに埋め込んで見る（ditaa、C4 model 編）
  10. Antora で PlantUML 等の diagram を埋め込む
  11. Antora で生成するドキュメントサイトに antora-lunr で検索機能を追加する