MarkdownとPandocでお手軽なドキュメント管理

こんにちは。
朝の一杯がかかせないtomita@atuwebです。

熱いコーヒーを注ぐマグは、iittala(イッタラ)のTeemaです。 ブレません。

---

プロジェクトのドキュメント管理はまともに取り組むと膨大なコストがかかってしまいます。

「 デバッグよりも、ドキュメント作成よりも、ガシガシ実装している方が楽しい 」と思うのは、ほとんどのプログラマが同じでしょう。
だからこそ、周辺の作業はできるだけ短時間でこなしてしまいたいものです。

先日「 Markdownでドキュメントを管理したら楽だなー 」と考えましたので、調べたことをまとめてみます。

Markdownはコストが低い

Markdown使ってますか？

Markdownとは「文書を記述するための軽量マークアップ言語」です。
言語というと大げさに感じるくらい、 覚えることが少なく かつ、簡単にテキストを整えることができることがメリットです。

これをドキュメント管理に利用しない手はありません。

ドキュメントを読むのはエンジニアだけではない

そこで問題になってくるのが、非エンジニアさんへの対応です。

なかなか非エンジニアのお客さまに「Markdownビューア入れればOKですよ」とは言えませんよね。

そういったことを踏まえると、Markdownではなく、他にドキュメントを閲覧できる方法を提供することがベターです。

エディタによってはプレビューをHTML出力することもできますが、ドキュメントの枚数が多くなった時のことを考えると、これは現実的な対応方法ではないことがわかると思います。
面倒くさいと感じたら、やがてやらなくなるのが常です。

Pandocで変換する

そこで、ドキュメント変換ツールPandocです。

PandocはHaskell製のドキュメント変換ツールで、対応フォーマットが豊富なことが特徴です。

Pandocをインストールする

以下を参照してインストールを行ってください。

私はMacの環境にbrewでインストールしました。

brew install pandoc

依存ライブラリも少しあって、 インストール完了まで30分程度かかっていました。。。

ドキュメントを変換する

$ pandoc -o input.md output.html

---

Pandocの導入については、こちらの記事を熟読いたしました。

ディレクトリごと処理する

Pandocはファイルを1点ずつ処理するコマンドのため、単体でディレクトリごと処理することは難しそうです。

しかし、なんてことはありません。
ディレクトリごと処理するようにシェルを組めば良いだけの話です！

探してみると、ズバリそのものを公開されている方がいらっしゃいました。

finelagusaz/md2html.shをほぼそのまま利用しております。 ありがとうございます。

最終的にcss指定などを追加してpancodコマンドをこのようにしております。

pandoc -f markdown_github -i $mdfile -o $htfile -c github.css -t html5 -s

さらに、出力ディレクトリを分けるなど、カスタマイズをするとさらに使い勝手が良くなりますね。

実例：API仕様書を管理する

ディレクトリ構成例

repository
  |- webapp
  |   |- プログラム類
  |  
  |- documents
      |- API仕様書
          |- structure
          |   |- 構造体1.md
          |   |- 構造体2.md
          |   :
          |
          |- index.md
          |- Overview.md
          |- API1.md
          |- API1.md
          :

API仕様書_カード詳細取得.md

## API名
カード詳細取得

## URL
/user/card

## リクエスト
### メソッド
GEST

### パラメーター
- user_id
- card_id

## レスポンス
### 構造

{ “status” : int, “message”: string, “params” : { “userCard” : {構造体:UserCard} } }

## エラーコード
- 101 : ユーザID不正
- 102 : カードID不正

API仕様書_構造体UserCard.md

## 構造体
### 構造体名
UserCard

### 構造
'```
userCard : {
  "userId" : int,
  "cardId" : int,
  "atk"    : int,
  "def"    : int
}
'```


### 型
|Key|Value型|説明|備考|
|:--|:--|:--|:--|
|userId|int|ユーザID||
|cardId|int|カードID||
|atk|int|攻撃力|1-999|
|def|int|防御力|1-999|

変換

$ cd path/to/repository
$ sh comvert.sh documents/API仕様書

こんな感じでコンバートを実行すると、API仕様書ディレクトリ以下にHTMLが出力されます。

index.mdに各ドキュメントのリンクを用意しておけば、ブラウザで各ドキュメントを横断的に閲覧できストレスもありません。
このindex.mdは手動で編集をしていますが、ファイルの増減が激しければ自動化を検討してコスト減を真面目に考える必要があります。

さらに拡張する

正直にMarkdownから様々なフォーマットに変換できますので、ちょこっとスクリプトを書き足すことで利用できるシーンはかなり広がります。

具体的にはこんな物を用意すればプログラムの補助まで補うことがで、全体のコスト減に貢献できるのではないでしょうか。

• プログラムのenumを舐めて表にまとめる
• mdファイルからJavaのBeanや構造体.hを生成する

おわりに

Markdownに慣れてくると、素早くドキュメントを管理できます。
私もMarkdownの使い始めは、最初はしょっちゅう記法を忘れてしまいqiitaのチートシートをチェックしていました。

良いものは積極的に使っていきましょう。

---

2017年09月23日：レイアウト崩れを修正