Gradle+Asciidoc+PlantUMLでHTML&PDFビルド環境を整える

Warning: count(): Parameter must be an array or an object that implements Countable in /home/crude/xn--fhqq99a3lb.jp/public_html/wp-content/themes/cocoon-master/lib/shortcodes-amazon.php on line 745

最近Asciidocでドキュメントを書くのが流行りなんて話も聞きますし、お仕事でも少しだけ書かせて頂いた事があるのですが、手元でビルドするやり方をちゃんと把握していないなと思い、改めてまとめてみることにしました。CI等を考えてGradleプロジェクトとして作成し、挿図にはPlantUMLを使うよく聞くやり方です。

Index

使用ソフトウェア
作成サンプル
build.gradle
adocファイルの作成
参考
まとめ
こんな本もあります

使用ソフトウェア

今回構築にあたって使用したソフトウェア/ライブラリおよびバージョンは以下の通りです。

asciidoctor-gradle-plugin（1.5.3）
asciidoctorj-diagram（1.5.8）
asciidoctorj-pdf（1.5.0-alpha.15）
gradle（4.8.1）
Graphviz（2.38）

記事執筆時（2018/07/15）のasciidoctor系のライブラリの最新バージョンは使用していません。上記のバージョンよりも新しいものを使用すると警告やビルドが安定しないなどの事象が見られましたのでバージョンを下げて使用しています。詳細は未調査。

Graphvizはビルドを実行する環境にインストールの上、パスを通しておいてください。64bit版のWindowsの場合はC:\Program Files (x86)\Graphviz2.38\binです。

作成サンプル

今回説明する内容はこちらに実装して置いてあります。

kawakamitor/blog-materials

Contribute to kawakamitor/blog-materials development by creating an account on GitHub.

ほぼ自分用な感じですね(^_^;)

build.gradle

私の場合はbuild.gradleを以下のように作成しました。

buildscript {
    ext {
        asciiDoctorGradlePluginVersion = "1.5.3"
        asciidoctorjDiagramVersion = "1.5.8"
        asciidoctorjPdfVersion = "1.5.0-alpha.15"
    }
    repositories {
        jcenter()
    }
    dependencies {
        classpath("org.asciidoctor:asciidoctor-gradle-plugin:${asciiDoctorGradlePluginVersion}")
        classpath("org.asciidoctor:asciidoctorj-diagram:${asciidoctorjDiagramVersion}")
        classpath("org.asciidoctor:asciidoctorj-pdf:${asciidoctorjPdfVersion}")
    }
}

apply plugin: 'org.asciidoctor.convert'
apply plugin: 'org.asciidoctor.gradle.asciidoctor'

asciidoctor {
    dependsOn 'clean'
    requires = ['asciidoctor-diagram']
    backends = ['html5', 'pdf']
    outputDir = file('build')
    separateOutputDirs = false
    attributes = [
            "imagesoutdir": "${outputDir}/images",
            "imagesdir"   : "${outputDir}/images"
    ]
}

defaultTasks 'asciidoctor'

前述の通り、asciidoctor系のライブラリは少し前のバージョンを指定しています。各ライブラリのバージョンはこちらをご参照ください。

maven - Maven - Bintray

maven, by asciidoctor. Smartly served to you by Bintray.com. Libraries and plugins for processing AsciiDoc on the JVM using Asciidoctor and JRuby.

asciidoctorの設定は好みもありますが以下のポイントを意識しました。

requiresにasciidoctor-diagramを指定し、PlantUMLによる挿図を有効化
backendsにHTMLとPDFの両方をビルドするよう設定
アウトプットの出力階層が深くなるのが嫌だったのでoutputDirを指定
HTMLとPDFを別ディレクトリに出力する必要が無いのでseparateOutputDirs = falseを指定
アウトプットディレクトリに併せて、imagesoutdirとimagesdirを指定

細かいattributesはadoc側で指定すればいいかなと思いましたが、使い方に併せて検討してみてください。詳細なオプションはプラグインの説明をご確認ください。

Asciidoctor Gradle Plugin | Asciidoctor

Asciidoctor Diagram | Asciidoctor

adocファイルの作成

続いてadocファイルの作り方について説明します。

ファイルの構成

特に指定しない場合、デフォルトの入力ディレクトリ（src/doc/asciidoc）配下の全てのadocファイルがビルドされ、それぞれに対してHTMLとPDFが生成されますが、adocファイルは分割して作成したいもののビルド結果は1つにまとめたいですよね。

やり方は2つあるかと思います。

ルートのadocをbuild.gradleに指定する
ルートのadoc以外のファイル_で始まるファイル名にする

お好みで良いかなぁ～と思います。build.gradleでの指定方法はこんな形です。

asciidoctor {
  // 省略
  sources {
    include 'toplevel.adoc', 'another.adoc', 'third.adoc'
  }
  // 省略
}

今回作成したサンプルでは後者のルート以外のadocファイルをアンダースコア始まりにしてみました。いたずらしそうな人が多い場合はちゃんと指定したほうが良いんですかね。

ルートドキュメントの作成

ルートとなるadocファイルには全体的な設定やドキュメント全体の説明を載せておくと良いかと思います。ビルド結果のイメージとしては、Asciidocのリファレンスと同じく左側に目次があるSingleHTMLをイメージしています。

Asciidoctor User Manual

This guide describes the Asciidoctor attributes, values, and layout options available for producing a customized and polished document.

こんなのですね。

オプション（attribudes）はこんな感じに設定してみました。

:lang: ja
:doctype: book
:docname: Asciidoc Blank
:imagesdir: ./images
:sectnums:
:toc: left
:toclevels: 3
:icons: font
:source-highlighter: highlightjs
:author: Auther
:email: auther@mail.com

とりあえず目次を左側に表示、目次の階層は3階層まで、セクション番号を表示、脚注のアイコンはCSSで表示、コードハイライトはこのブログに併せてhighlightjsを使用、くらいしか気にしていませんが、オプションは様々指定可能です。

Asciidoctor User Manual

This guide describes the Asciidoctor attributes, values, and layout options available for producing a customized and polished document.

ビルトインラベルを変更したい（「Last updated」 → 「最終更新日時」にしたいなど）場合は、この辺りを参照して設定すれば良いです。

Asciidoctor User Manual

This guide describes the Asciidoctor attributes, values, and layout options available for producing a customized and polished document.

また、セクション毎にadocファイルを作成し、ルートドキュメントから読み込む形にしています。

include::_sec01_basic_writing_style.adoc[]

こんな感じでOKですね。

PlantUMLの書き方

例えばシーケンス図を書くときはこんな感じになります。

[plantuml, diag-sequence-sample]
----
@startuml
ClassA -> ClassB: Call
ClassB -> ClassC: Call
ClassC --> ClassB: Response
ClassB --> ClassA: Response
@enduml
----

これが