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 とは

AsciiDoc Home Page 軽量マークアップ言語の一つ。この分野では Markdown が有名ですね。しかしMarkdown は方言が多く、一言でMarkdown 対応といっても対応している表現、対応していない表現があって混乱することが多いです。 気軽に残すメモなどの用途に向いているのかなという印象です。 その点 AsciiDoc は、使える表現が仕様化されており、仕様書などある程度の規模の文章を書いているのに向いているように思います。特にテーブルはCSVが使えたり、一つのセルで複数行に渡るものが書けたりするのがとても気に入ってます。 AsciiDoc については別記事も書いてますのであわせてご覧ください。 * AsciiDoc の何がいいの? => AsciiDocを全力で勧める 4つの理由 * AsciiDoc は Markdown より難しいんじゃ? => AsciiDoc vs Markdown 比較チートシート

PlantUML とは

PlantUML UMLをテキストで記載できるようにしたもの。シーケンス図、ユースケース図、クラス図、アクティビティ図、コンポーネント図、状態遷移図、オブジェクト図などUMLを一通りテキストで記載できます。 クラス図などはクラスの配置とかではなく論理的な構造を図示したものなので、配置に気を使ってマウスでカチカチしたくないです。その点、PlantUML はテキストで構造をガシガシ記載しつつ、できあがったクラス図をプレビューするということができるので、頭の中を整理できて作ってて気持ちがいいです。 手に馴染んだテキストエディタで作れるのもありがたい。

mermaid.js とは

mermaid.js JavaScript のフローチャートライブラリ。図をテキストで記述することの利点は、PlantUMLと基本同じです。こちらはUMLよりももっと概念的なフローチャートを書いたりする時に使っています。 使ったことはないですがガントチャートとかも書けるらしいです。 mermaid.js のフローチャートについては別記事で書き方を記載しました。

準備

必要なライブラリ、ツール類をインストールをインストールしていきます。ruby はインストールしてる前提です。 AsciiDoc をHTML化するツール asciidoctor、AsciiDoc 中に PlantUML を記述できる拡張 asciidoctor-diagram は gem でインストールします。AsciiDoc を PDF 化するツール asciidoctor-pdf も gem ですが、まだ正式リリースでは無いみたいなので --pre をつけてインストールします。 mermaid は npm でインストールします。phantomjs に依存しているため、こちらも npm でインストールします。

AsciiDoc を PDF で出力する

AsciiDoc を書いてみます。下記の内容で、sample.adoc を作ります。 下記コマンドにて PDF を出力します。
  • -n でセクションに自動で番号を振ります。
  • -a toc で 目次(Table Of Contents) を追加します。
  • -r asciidoctor-diagram で PlantUML などの図形拡張を使います。
できた PDFはこちら AsciiDoc 標準の部分に加えて、PlantUMLも直接記述できます。 さすがにPlantUMLは別ファイルで扱った方がいいな・・・という場合は、下記のような別ファイルにすることも可能です。AsciiDoc標準のincludeとの合わせ技です。 sample.puml 図自体の規模が大きい場合は、図だけでプレビューできるのでこれはこれで便利です。

プレビューはどうする?

上記で、PDFを出力することは作業中は成果物をプレビューしつつ作業したいですよね。 プレビュー環境はいくつか選択肢がありますが、私はAtomを使っています。 使うのは、asciidoctor-preview というAtomのプラグインです。asciidoctor-previewはその名の通り、asciidoctorを出力したものをプレビューできるので、今回のPlantUMLのようなasciidoctorの拡張を使っている場合でも結果がプレビューできます。asciidoc-preview の方はPlantUMLが描画できませんでした・・・ Atom は PlantUMLやmermaid 単体もプレビューできる環境があり、ほぼAtomだけで作業を完結できるので重宝します。

フォントなど、見た目を変えたい場合は?

別記事を書きましたのでそちらを参照ください。 AsciiDoc を PDF 化する時の日本語フォントを指定する

さいごに

これで基本すべてテキストで記述して、提出時はPDFでというワークフローで作業できました。テキストベースだと差分確認とかもしやすいので、個人的には出来る限りテキスト管理していきたいものです。 とは言え、AsciiDocをそのまま人に渡しても見れる人は少ないので、提出する時はPDFにして多くの人に見てもらえます。 自分が作業している時は慣れたテキストエディタで作業できるので、ストレスなく作業できました。
最後まで読んでいただきありがとうございます。 このブログを「いいな」と感じていただけましたら、Twiter にてフォローいただけるとうれしいです。ブログ更新情報などもお届けします。



りゅーた
フリーランスのエンジニアしてます。Android、iOS アプリの開発、対向サーバの開発、C/C++のライブラリ開発が現在のメイン。趣味はテニス・ゲーム・自転車。2児の父

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA