AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
以前からテキストベースで仕様書(PDF)などを管理したいと思っていたのですが、ようやくその環境が整い、一度実際に運用してみてかなりいい感じだったので紹介したいと思います。
- 基本テキストは AsciiDoc で記述する
- UML は PlantUML で記述する
- フローチャートとかは必要に応じて mermaid.js も使う
- つまり基本テキストで表現・管理できるものはテキストで書く
- 成果物は PDF形式。目次(Table of Contents) はつける。
動作確認環境
- macOS Sierra 10.12.3
- ruby 2.3.1
- Asciidoctor 1.5.5
- Asciidoctor PDF 1.5.0.alpha.14
- Asciidoctor Diagram 1.5.4
- mermaid 7.0.0
AsciiDoc とは
軽量マークアップ言語の一つ。この分野では Markdown が有名ですね。しかしMarkdown は方言が多く、一言でMarkdown 対応といっても対応している表現、対応していない表現があって混乱することが多いです。
気軽に残すメモなどの用途に向いているのかなという印象です。
その点 AsciiDoc は、使える表現が仕様化されており、仕様書などある程度の規模の文章を書いているのに向いているように思います。特にテーブルはCSVが使えたり、一つのセルで複数行に渡るものが書けたりするのがとても気に入ってます。
AsciiDoc については別記事も書いてますのであわせてご覧ください。
* AsciiDoc の何がいいの？ => AsciiDocを全力で勧める 4つの理由
* AsciiDoc は Markdown より難しいんじゃ？ => AsciiDoc vs Markdown 比較チートシート
PlantUML とは
UMLをテキストで記載できるようにしたもの。シーケンス図、ユースケース図、クラス図、アクティビティ図、コンポーネント図、状態遷移図、オブジェクト図などUMLを一通りテキストで記載できます。
クラス図などはクラスの配置とかではなく論理的な構造を図示したものなので、配置に気を使ってマウスでカチカチしたくないです。その点、PlantUML はテキストで構造をガシガシ記載しつつ、できあがったクラス図をプレビューするということができるので、頭の中を整理できて作ってて気持ちがいいです。
手に馴染んだテキストエディタで作れるのもありがたい。
mermaid.js とは
JavaScript のフローチャートライブラリ。図をテキストで記述することの利点は、PlantUMLと基本同じです。こちらはUMLよりももっと概念的なフローチャートを書いたりする時に使っています。
使ったことはないですがガントチャートとかも書けるらしいです。
mermaid.js のフローチャートについては別記事で書き方を記載しました。
準備
必要なライブラリ、ツール類をインストールをインストールしていきます。ruby はインストールしてる前提です。
AsciiDoc をHTML化するツール asciidoctor、AsciiDoc 中に PlantUML を記述できる拡張 asciidoctor-diagram は gem でインストールします。AsciiDoc を PDF 化するツール asciidoctor-pdf も gem ですが、まだ正式リリースでは無いみたいなので –pre をつけてインストールします。
|
1 2 3 4 |
$ gem install asciidoctor $ gem install asciidoctor-diagram $ gem install --pre asciidoctor-pdf |
mermaid は npm でインストールします。phantomjs に依存しているため、こちらも npm でインストールします。
|
1 2 3 |
$ npm install -g phantomjs $ npm install -g mermaid |
AsciiDoc を PDF で出力する
AsciiDoc を書いてみます。下記の内容で、sample.adoc を作ります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 |
= 素敵なテキストベース仕様書の例 :source-highlighter: coderay == はじめに 本書はAsciiDoc、PlantUML、mermaid などを使ったテキストベース仕様書の例を示すことを目的とする。 == AsciiDocの記法(基本) AsciiDocの記法について記載する。なお、ここで紹介するのほんの一部の記法のみなので詳細は link:http://www.methods.co.nz/asciidoc/[公式ページ]を参照。 === セクション セクションは行頭を "=" で始める。"="の数でレベルを表現 === リスト * リストは * ではじめる ** *の数でレベルを表現する *** level3 === 番号付きリスト . 番号付きリスト .. こちらも同じく .. の数でレベルを表現 === テキスト修飾 下記のようなものが使える *太字* _斜体_ (C) などなど多彩。link:http://powerman.name/doc/asciidoc#_level_1[AsciiDoc cheetsheet]を参照 === テーブル [.center,options="header,autowidth"] |======================= | 項番 | 内容 | 1 | .centerで表示位置を中央に | 2 | header でヘッダつき | 3 | autowidth で幅を自動で調整してくれたり | 4 | 一つの + セル内に + 複数行で + 書くことも + できる |======================= === ブロック .コードブロックの例 [source,ruby] ---- require 'optparse' opt = OptionParser.new opt.on('-a') {|v| p v } opt.on('-b') {|v| p v } opt.parse!(ARGV) p ARGV ruby sample.rb -a foo bar -b baz # => true true ["foo", "bar", "baz"] ---- コードハイライトもされるので、見た目も良い <<< === 改ページ <<< で改ページ。PDFを出力する時にたまに使う。 === PlantUML PlantUML を直接書ける .PlantUMLの例 [plantuml] .... class 会社員 class 技術社員 class 会社 会社員 <|-- 技術社員 会社 -> 会社員 : 給与を払う .... === mermaid mermaid も直接書ける .mermaidの例 [mermaid] .... graph LR; AsciiDocテキスト -- asciidocotor-pdf --> PDF仕様書; PlantUMLテキスト -- PlantUML --> png画像; png画像 -- asciidoctor-pdf --> PDF仕様書; .... |
下記コマンドにて PDF を出力します。
|
1 2 |
$ asciidoctor-pdf sample.adoc -n -a toc -r asciidoctor-diagram -o sample.pdf |
- -n でセクションに自動で番号を振ります。
- -a toc で 目次(Table Of Contents) を追加します。
- -r asciidoctor-diagram で PlantUML などの図形拡張を使います。
できた PDFはこちら
AsciiDoc 標準の部分に加えて、PlantUMLも直接記述できます。
|
1 2 3 4 5 |
[plantuml] .... PlantUMLテキスト .... |
さすがにPlantUMLは別ファイルで扱った方がいいな・・・という場合は、下記のような別ファイルにすることも可能です。AsciiDoc標準のincludeとの合わせ技です。
|
1 2 3 4 5 |
[plantuml] .... include::sample.puml[] .... |
sample.puml
|
1 2 3 4 5 6 |
class 会社員 class 技術社員 class 会社 会社員 <|-- 技術社員 会社 -> 会社員 : 給与を払う |
図自体の規模が大きい場合は、図だけでプレビューできるのでこれはこれで便利です。
プレビューはどうする？
上記で、PDFを出力することは作業中は成果物をプレビューしつつ作業したいですよね。
プレビュー環境はいくつか選択肢がありますが、私はAtomを使っています。
使うのは、asciidoctor-preview というAtomのプラグインです。asciidoctor-previewはその名の通り、asciidoctorを出力したものをプレビューできるので、今回のPlantUMLのようなasciidoctorの拡張を使っている場合でも結果がプレビューできます。asciidoc-preview の方はPlantUMLが描画できませんでした・・・
Atom は PlantUMLやmermaid 単体もプレビューできる環境があり、ほぼAtomだけで作業を完結できるので重宝します。
フォントなど、見た目を変えたい場合は？
別記事を書きましたのでそちらを参照ください。
AsciiDoc を PDF 化する時の日本語フォントを指定する
さいごに
これで基本すべてテキストで記述して、提出時はPDFでというワークフローで作業できました。テキストベースだと差分確認とかもしやすいので、個人的には出来る限りテキスト管理していきたいものです。
とは言え、AsciiDocをそのまま人に渡しても見れる人は少ないので、提出する時はPDFにして多くの人に見てもらえます。
自分が作業している時は慣れたテキストエディタで作業できるので、ストレスなく作業できました。
最後まで読んでいただきありがとうございます。 このブログを「いいな」と感じていただけましたら、Twiter にてフォローいただけるとうれしいです。ブログ更新情報などもお届けします。
Follow @ryuta461
この記事をシェアする