ITエンジニア/デザイナ向けにオープンソースを毎日紹介

FlatdocはHTML/JavaScript製、Creative Commonsのオープンソース・ソフトウェアです。

ソフトウェアを作るのは好きでも意外と面倒に感じてしまうのがドキュメントです。さらにHTMLで、Webブラウザでも見えるようにしておかないと使ってもらうこともないでしょう。そこでREADMEファイルから見栄えのいいHTMLドキュメントを生成してくれるFlatdocを使ってみましょう。


こちらがベースになるテンプレートです。3カラムのシンプルな感じです。


そしてこちらがソース。GitHubのユーザ名、リポジトリ名を指定します。


そうするとこのようなドキュメントが生成されます。READMEの内容を自動的に読み込んで描画しています。


表示についてはオプションを使ってカスタマイズができるようになっています。


JavaScriptのフックも使えますのでより広範囲なカスタマイズも可能です。

仕組みはGitHubのAPIを使ってリポジトリのREADMEを読み込み、その内容を解析して3カラムに展開しています。見出しの項目が左側に並び、そのコンテンツが中央に、そしてコマンドやコード、引用文などが右に出るようになっています。分解されることで可読性高い文書が生成されるのが特徴です。


MOONGIFTはこう見る

ライブラリのドキュメントというのはそれほど特徴を出す必要がありません。むしろライブラリごとに見栄えが違うと情報を探すのも大変になってしまいます。APIドキュメントなどは一定のフォーマットに沿って書かれている方が良いでしょう。数年前まではそういった統一感があったように思うのですが、GitHubの登場以後カジュアルになっていく中で徐々に統一性がなくなっているように感じます。

しかしそんな中だからこそ、新しい統一フォーマットが求められているのかも知れません。その一つとして注目したいのがMarkdownやreStructuredText、Textileと言えます。これまでのプログラミング言語に依っていたドキュメント記法が統一されれば、どんなプログラミング言語でも同じ体裁のドキュメントとしてみられるのは便利そうです。

Flatdoc

rstacruz/flatdoc · GitHub

 

MOONGIFTの関連記事

コメント

  • DevRel
  • Com2