最近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）
C:\Program Files (x86)\Graphviz2.38\binです。作成サンプル
今回説明する内容はこちらに実装して置いてあります。
ほぼ自分用な感じですね(^_^;)
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系のライブラリは少し前のバージョンを指定しています。各ライブラリのバージョンはこちらをご参照ください。
asciidoctorの設定は好みもありますが以下のポイントを意識しました。
requiresにasciidoctor-diagramを指定し、PlantUMLによる挿図を有効化backendsにHTMLとPDFの両方をビルドするよう設定- アウトプットの出力階層が深くなるのが嫌だったので
outputDirを指定 - HTMLとPDFを別ディレクトリに出力する必要が無いので
separateOutputDirs = falseを指定 - アウトプットディレクトリに併せて、
imagesoutdirとimagesdirを指定
細かいattributesはadoc側で指定すればいいかなと思いましたが、使い方に併せて検討してみてください。詳細なオプションはプラグインの説明をご確認ください。
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をイメージしています。
こんなのですね。
オプション（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を使用、くらいしか気にしていませんが、オプションは様々指定可能です。
ビルトインラベルを変更したい（「Last updated」 → 「最終更新日時」にしたいなど）場合は、この辺りを参照して設定すれば良いです。
また、セクション毎に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 ----
これが
こうなるわけですね。
なお、PlatntUMLではUML各種＋αの挿図が可能です。詳細はこちらをご確認ください。
個人的にはシーケンス図とアクティビティ図があれば良いですかねぇ。それ以外は普通にお絵かきしたほうが良いものが多い気もします。とはいえ、テキストベースで管理できるものは多いに越したことはありませんからね。
参考
今回は標準的なパターンでビルド可能な雛形を用意しておこうというモチベーションではじめましたが、ビジネス的にちゃんとしたドキュメントを生成できるように取り組んでおられる方もいらっしゃるみたいで。
ちゃんとパワーを掛けてこういった取り組みを会社としてやっていける・・・会社には残念ながら在籍していないので辛いところではありますが、いつかこんなようなこともできると良いかもしれませんね。
まとめ
デフォルトのデザインでビルドするだけ（それでもかなりいいデザインに仕上がっていると思いますが）なら簡単にGradleを使用して実現できますね。
Asciidocは比較的書きやすくドキュメントツールとしては悪くないと思いますので、メモよりはちょっとリッチなドキュメントを付けたい、なんてときは重宝するんじゃないでしょうか。
自分としてもすぐに書き始められる雛形を用意しておきたかったので今回取り組んでみました。ご覧頂いた方の何かの参考になれば幸いです。
この記事に対するコメント