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

Asciidoc

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

使用ソフトウェア

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

  • 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の設定は好みもありますが以下のポイントを意識しました。

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

細かい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
----

これが

こうなるわけですね。

plantumlブロック開始の際に、カンマ区切りで生成されるファイル名と拡張子を指定出来ます。ファイル名を省略するとランダムな名称が生成されますが、特定出来なくなるので設定しておいたほうが良いかと思います。拡張子は省略するとpngが指定されますが、特に要件の無い限りそのままで良いと思います。

なお、PlatntUMLではUML各種+αの挿図が可能です。詳細はこちらをご確認ください。

Open-source tool that uses simple textual descriptions to draw UML diagrams.
Easily create UML Diagrams from simple textual description. There are also numerous kind of available diagrams. It's also possible to export images in PNG, LaTe...

個人的にはシーケンス図とアクティビティ図があれば良いですかねぇ。それ以外は普通にお絵かきしたほうが良いものが多い気もします。とはいえ、テキストベースで管理できるものは多いに越したことはありませんからね。

参考

今回は標準的なパターンでビルド可能な雛形を用意しておこうというモチベーションではじめましたが、ビジネス的にちゃんとしたドキュメントを生成できるように取り組んでおられる方もいらっしゃるみたいで。

asciidoctor-pdfで社内ドキュメントを書こう - Qiita
この投稿は ( の 12日目の記事です。 この記事に書かれた見識は個人のものであり...

ちゃんとパワーを掛けてこういった取り組みを会社としてやっていける・・・会社には残念ながら在籍していないので辛いところではありますが、いつかこんなようなこともできると良いかもしれませんね。

まとめ

デフォルトのデザインでビルドするだけ(それでもかなりいいデザインに仕上がっていると思いますが)なら簡単にGradleを使用して実現できますね。

Asciidocは比較的書きやすくドキュメントツールとしては悪くないと思いますので、メモよりはちょっとリッチなドキュメントを付けたい、なんてときは重宝するんじゃないでしょうか。

自分としてもすぐに書き始められる雛形を用意しておきたかったので今回取り組んでみました。ご覧頂いた方の何かの参考になれば幸いです。

 

この記事に対するコメント