Markdown による中規模ドキュメンテーションシステムについて調べた。
(追記)
タイトルを "【緩募】Markdownによる中規模ドキュメンテーションシステム" から変えました。
(更に追記)
後日談 => Hugo で "bootie-docs" というドキュメンテーション用のテーマを作った #Hugo - weblog of key_amb
下のような疑問を持ったのがきっかけで、Twitter でつぶやきつつ調べたりしていました。
結論としては下の方に書いてある通り、静的サイトジェネレータの Jekyll や MkDocs あたりを使うのがよさそうです。
最初、Sphinx が手堅いだろうと思いましたが、今や Sphinx でなければならない理由はないかな、と。
そこそこの規模のソフトウェアドキュメントをテキストベースで書くのに最適なツールなんですかね? Sphinx はカタいのですが、できればMarkdownで管理したい。
— きいあむ → @progrhyme (@key_amb) 2015年3月31日
Pandoc 使えそうなのですけど、複数ファイルで目次作りたいとかなるとちょっと手作業でMakefileこさえたりしないといけなさそう。
— きいあむ → @progrhyme (@key_amb) 2015年3月31日
こういうの見つけました。使えそうではあります。/ chutsu/ditto : https://t.co/BNDn7RsuMo
— きいあむ → @progrhyme (@key_amb) 2015年3月31日
これも使えるかも。/ MultiMarkdown : http://t.co/sFKZwjpqe4
— きいあむ → @progrhyme (@key_amb) 2015年3月31日
Pandoc や MultiMarkdown について補足
上が本家サイトで、日本語の情報は @sky_y さんがよくまとめて下さっています。
http://sky-y.github.io/site-pandoc-jp/:title
多様な入出力に対応しているところが Fluentd / Embulk あたりに似ていて面白いですね。
活発に開発が行われているようです。
が、Pandoc にしろ MultiMarkdown にしろ、単独のファイルを Markdown => HTML に変換することは問題ないようですが、そこそこ構造化されたドキュメント群を生成するには一工夫要りそうな印象です。
その点でもやはり Sphinx はカタくて、特に設定しなくても Qiita に書いたような手順(下)で簡単にドキュメントの雛形から HTML 群を生成するところまでイケました。
逆に、Pandoc OR MultiMarkdown を使って、構造化されたドキュメント群を生成する支援ツールを作るのもいいかもしれませんね。
Twitter でのやりとり
ここまで書いたところ、Twitter で @sonots さんからコメントもらいました。
@key_amb octopress とか hugo とかブログ系ならいっぱいありますね。ドキュメント集約に向いてるかは微妙ですが。
— そのっつ (Naotoshi Seo) (@sonots) 2015年4月1日
ブログ形式だとちょっとドキュメントに向かないかもですが、 Octopress のドキュメントも Octopress で書かれてるようだし、問題ない気もします。
…というわけで、これをヒントに静的サイトジェネレータをあさっていたら、まさしくドキュメンテーション用途のものがありました。
そのものずばりのありました。/ MkDocs / http://t.co/eNMralHRIQ #markdown #mkdocs
— きいあむ → @progrhyme (@key_amb) 2015年4月2日
また、Jekyll の場合、jekyll-docs-templateというテンプレートがあるので、これを使うとよさそうです。
静的サイトジェネレータについては、下記サイトを参考に探しました。
その他、何か知見をお持ちの方はお知らせいただけるとうれしいです。