AsciiDocによる継続的ドキュメント開発〜１．インストールと基本的な使い方

はじめに

ドキュメントを書くための言語としておそらく今一番ポピュラーなのは Markdown だと思いますが、
かっちりした仕様書やユーザーマニュアルなど、より本格的なドキュメント作成にはやや機能不足と感じることがあります。

私も以前、ドキュメントを Gitbook で作れないか検討したことがあったんですが
表を書くのがめんどくさかったり、図のキャプションなどに対応していなかったことから断念しました。

そこで、今回は Markdown よりも表現力の高い言語として知られる AsciiDoc を試してみます。
AsciiDoc は O'reilly でも採用されているほか、Pro Git や JavaScript Promise の本などの非常に完成度の高い技術ドキュメントが AsciiDoc で書かれています。

（参考記事）
・テクニカルライティングの未来を先取りー Asciidoc フォーマットと GitHub を使って技術書 Pro Git を共同執筆 — Japanese Official — Medium
・JavaScript Promiseの本を書きました | Web Scratch

やりたいことは色々とあるんですが、まずはインストールと基本的な使い方を学ぶところまでやってみます。

参考書籍

この書籍を読みながら勉強中です。
本屋でざっと流し読みした感じ、AsciiDoc で書いたドキュメントを GitHub で管理したり、校正ツールや CI を導入したりと
自分のやりたいことがそのものずばりって感じです。

ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによるモダンライティング]

作者:伊藤敬彦,吉村孝広
技術評論社

Amazon

インストール

Asciidoctor という AsciiDoc の Ruby 実装をインストールします。 AsciiDoc のリポジトリを見ると HTML などに変換するプロセッサーも用意されているようですが、
実際に AsciiDoc を HTML や pdf に変換するためのプロセッサーは Asciidoctor の方が一般的のようです。

ブログを書いた時点での Ruby のバージョンは以下です。

$ ruby -v
ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-darwin14]
$ gem -v
2.4.5.1
$ bundle -v
Bundler version 1.12.5

インストール方法は、普通に

$ gem install asciidoctor

を実行するか、または Gemfile を用意し

source 'https://rubygems.org'
gem 'asciidoctor'

と記述した後、

$ bundle install

を実行します。

$ bundle install
Fetching gem metadata from https://rubygems.org/
Fetching version metadata from https://rubygems.org/
Resolving dependencies...
Installing asciidoctor 1.5.4
Using bundler 1.12.5
Bundle complete! 1 Gemfile dependency, 2 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.

インストールすると asciidoctor というコマンドが実行可能になります。

基本的な使い方：HTML, pdf, epub の作成

さっそく何かドキュメントを書いてみます。
拡張子は .adoc または .asciidoc にします。

= はじめての AsciiDoc ドキュメント

これは AsciiDoc で書かれたドキュメントです。

== セクション

``=`` から始まる行はセクションの見出しになります。 +
``==``, ``===``, ... のように `=` を重ねるとレベルが1つ下がります。

== テーブル（表）

.テーブル見出し

|=======================
|Col 1|Col 2      |Col 3
|1    |Item 1     |a
|2    |Item 2     |b
|3    |Item 3     |c
|=======================

CSV 形式で書くこともできます。

[format="csv"]
|======
1,2,3,4
a,b,c,d
A,B,C,D
|======

== ソースコード

[source, javascript]
----
export default class MyComponent extends React.Component {
    render() {
        <div>Hello, World!</div>
    }
}
----

HTML への変換

HTML への変換は、asciidoctor コマンドを実行するだけです。

$ ls
sample-doc.adoc
$ asciidoctor sample-doc.adoc
$ ls
sample-doc.adoc sample-doc.html

生成した HTML はこちら。

f:id:dackdive:20160614013736p:plain

デフォルトのスタイルでもイイ感じですが、ソースコードが色付け（シンタックスハイライト）されてませんね。

ソースコードのシンタックスハイライト

http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#source-code を読むと、
ファイルの先頭で source-highlighter という変数を定義する必要があるようです。
また、シンタックスハイライト用のプラグインをいくつかの選択肢の中から選んでインストールする必要があります。

今回は coderay を選択します。

$ gem install coderay

でインストールした後、.adoc ファイルの先頭に以下を追記します。

:source-highlighter: coderay

この状態で HTML に変換すると、シンタックスハイライトが有効になります。

pdf への変換

HTML 以外の形式への変換は、別途プラグインをインストールする必要があります。
（Converters の項を参照）

pdf については asciidoctor-pdf をインストールします。

$ gem install asciidoctor-pdf

コマンドが asciidoctor-pdf になること以外は HTML の時と変わりません。

$ ls
sample-doc.adoc sample-doc.html
$ asciidoctor-pdf sample-doc.adoc
$ ls
sample-doc.adoc sample-doc.html sample-doc.pdf

生成した pdf がこれです。

f:id:dackdive:20160614023314p:plain

フォントなど、スタイルで気に入らない部分があるかもしれませんが CSS で調整可能のようです。これについてはまた今度。

epub への変換

epub については asciidoctor-epub3 をインストールします。
参考：How to Convert AsciiDoc to EPUB3 with Asciidoctor | Asciidoctor

まだ試せてないので今後の課題として。

（おまけ）エディタの設定

最後に、AsciiDoc を書きやすくするためにエディタも設定しておきます。
Atom の場合、公式ドキュメント
http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/#atom
にあるように、以下2つのプラグインをインストールすると良さそう。