dackdive's blog

新米webエンジニアによる技術ブログ。JavaScript(React), Salesforce, Python など

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

はじめに

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

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

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

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

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

参考書籍

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


インストール

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つのプラグインをインストールすると良さそう。

asciidoc-preview を入れると(Mac の場合)cmd + Shift + A でプレビューを表示させることができます。便利。

f:id:dackdive:20160614204519p:plain

一方、私は普段 Vim を使ってるんですが、Markdown ではできたプレビュー機能を提供するプラグインは見つからず。

参考:[vim]vimでmarkdownをリアルタイムプレビューできるようにする - dackdive's blog


触ってみた感想

Markdown ではネックだった表が CSV 形式で書けたり、ちょっと調べた感じだと図のキャプションに対応していたりと
Markdown では対応できなかったところをカバーしてくれそうな印象。

ただ、以前 Gitbook 調査していて gitbook-cli を使ったときは

$ gitbook serve

みたいなコマンドでローカルサーバーが立ち上がり、以後、ファイルの変更を検知して常に最新の HTML を表示することができていたんですが
Asciidoctor 単独だとそういった機能は提供していないので、gulp タスクなり Makefile なりでそのあたりも自分で作る必要がありそうです。


今後の予定

今後、こういったことをできるようにしていきたいです。

  • epub 形式に変換する
  • ローカルでドキュメントを書くときはローカルサーバーを起動し、自動で HTML 変換する
  • RedPen や textlint などの文法チェックツールを使用する
  • Travis CI などの CI ツールで GitHub にコミット時に自動的に文法チェックを実行する
  • CI の一環で、最新のドキュメントの HTML 版が常にどこかにデプロイされるようにする

とりあえず、今後も色々と機能追加していくと思うので、コードを GitHub に上げておきます。