GitHubのREADMEを可読性高く変換「Flatdoc」
FlatdocはHTML/JavaScript製、Creative Commonsのオープンソース・ソフトウェアです。
ソフトウェアを作るのは好きでも意外と面倒に感じてしまうのがドキュメントです。さらにHTMLで、Webブラウザでも見えるようにしておかないと使ってもらうこともないでしょう。そこでREADMEファイルから見栄えのいいHTMLドキュメントを生成してくれるFlatdocを使ってみましょう。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-29 12.05.14.1369976870.png)
こちらがベースになるテンプレートです。3カラムのシンプルな感じです。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-29 12.04.10.1369976874.png)
そしてこちらがソース。GitHubのユーザ名、リポジトリ名を指定します。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-29 12.06.20.1369976879.png)
そうするとこのようなドキュメントが生成されます。READMEの内容を自動的に読み込んで描画しています。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-29 12.06.51.1369976882.png)
表示についてはオプションを使ってカスタマイズができるようになっています。
[](http://images.moongift.jp/2013/05/Screenshot 2013-05-29 12.06.57.1369976887.png)
JavaScriptのフックも使えますのでより広範囲なカスタマイズも可能です。
仕組みはGitHubのAPIを使ってリポジトリのREADMEを読み込み、その内容を解析して3カラムに展開しています。見出しの項目が左側に並び、そのコンテンツが中央に、そしてコマンドやコード、引用文などが右に出るようになっています。分解されることで可読性高い文書が生成されるのが特徴です。
MOONGIFTはこう見る
ライブラリのドキュメントというのはそれほど特徴を出す必要がありません。むしろライブラリごとに見栄えが違うと情報を探すのも大変になってしまいます。APIドキュメントなどは一定のフォーマットに沿って書かれている方が良いでしょう。数年前まではそういった統一感があったように思うのですが、GitHubの登場以後カジュアルになっていく中で徐々に統一性がなくなっているように感じます。
しかしそんな中だからこそ、新しい統一フォーマットが求められているのかも知れません。その一つとして注目したいのがMarkdownやreStructuredText、Textileと言えます。これまでのプログラミング言語に依っていたドキュメント記法が統一されれば、どんなプログラミング言語でも同じ体裁のドキュメントとしてみられるのは便利そうです。