ツナワタリマイライフ

日常ネタから技術ネタ、音楽ネタまで何でも書きます。

クールでエレガントなドキュメント作成をするのにasciidocかなり良いぞ

はじめに

今月は技術学習をしないからってブログを書いちゃダメってわけじゃないんですがどうも滞ってますね。今年はドキュメント作成をクールでエレガントに!というすこぶる曖昧なテーマを掲げて活動しています。以下の本を読みました。

ドキュメント作成システム構築ガイド

githubでドキュメントを管理し、チームで開発する環境を整える。

次にredpenという構成ツールでドキュメントのテストをする。(赤ペン先生ですね。)

そしてコミットが起きるたびにredpenが動くようにTravisgithubと連携する。

できあがったドキュメントをasciidoctorでpdfやhtml、epubに変換する。

おもにこの4つをコアに説明しています。

markdown vs asciidoc

はてなブログもmarkdownで書けることでそもそもブログをたくさん書くようになりましたし、日常的にmarkdownを使っています。

asciidocについては以前より存在はしっていたものの、「改行が+は嫌や」という理由で避けていました。

この記事が良くまとまっています。

qiita.com

さて実際にasciidocを使ってみた感想ですが、多くの点でasciidocのほうが優れていると感じます。さらにmarkdownに慣れてるひとなら習得も容易です。実際に書きながらすぐに覚えることができると思います。

具体的にasciidocが優れている点は

  • tocが簡単
  • linkが簡単(url書くだけ)
  • tableが簡単
  • コメントが書ける

といったところが大きいと思いました。特にcsvをそのままテーブルにできるのはかなりいいなと。markdownはテーブル結構めんどくさいよね。

簡単なメモはもちろんこれまで通りmarkdownで、少し大きめな、仕様書レベルだと絶対にasciidocがいいです。

asciidocの環境

1番気になるのは環境面ですよね。Atomにasciidoc-previewというプラグインがあるんですが、それはインストールに失敗しました。

今は普通のエディタで書いて、firefoxのアドオンでプレビューしています。リアルタイムプレビューではありませんが、十分かなと。chromeにもあります。(がchromeのほうは動作しませんでした。)

最期にasciidocで書いたadocファイルをhtmlやpdfに変換するには、asciidoctor、asciidoctor-pdfを使います。以前はpython実装のasciidocで変換できたみたいですが、後発のruby製のasciidoctorのほうが楽だったのでそちらをおすすめします。

これはmaclinux環境が必要なので、windowsユーザにはいちいち持って行って変換するのが少しめんどくさいかもしれませんね。

gem installでいれて、コマンド叩くだけです。クッソ簡単。

iconを出す方法

asciidocでは NOTEやCAUTIONといった注意書きを書けます。これを書くと画像が出て欲しいんですが、デフォルトでは出ません。こんなやつです。

AsciiDoc Syntax Quick Reference | Asciidoctor

ページ右側の i のマークね。

asciidocのheaderのメタ部分に以下の記述を書けばokです

:icons: font

今後

今ちょうど会社で新しいツールを作っていて、その仕様書兼マニュアルをasciidocで書いています。デフォルトの変換でhtmlもpdfも十分綺麗に書けて満足してます。

今後はasciidoctor-diagramを使ってUMLを書けるようになりたい。これができればもうシステム設計も完全にasciidocで書けることになる。そしてasciidoctor変換時にstyle(css)指定もできるようになりたいですね。部内で広げていきたいと思います。