Sphinxお試し

ドキュメント大事です。
いつも何で書こうか試行錯誤するのですが、
結局、読む側の事を考慮すると、仕事上、Officeになってしまいます。

たまたま技術的なドキュメントを書く事になり、
HTMLで見れればいいと制約がゆるいので、気になっていたSphinxを試してみます。

・インストール
Linux(CentOS)に入れます。
Mac OS X, Linuxへのインストール — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
のままです。

・プロジェクトの作成
sphinx-quickstartの詳細説明 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会

ガーッとドキュメントを書いてみたんですが、いいですね。
画像がそんなに必要無い場合なんかは、プレーンテキストでバカバカ書けるので、
作業が止まらないというかストレスフリーです。
toctreeによる階層表現も、ちょっと馴染みづらいですが、慣れたら全然苦じゃないです。
何より、パワポで位置とか変に考えなくて済むので、ドキュメントを書く事に集中出来ます。
reSTもイマイチ把握しきれていませんが、必要最低限を覚えるのは、苦にならないですね。

ちなみに、編集→確認の作業ですが、
メインのPCがWindowsなので、
1.SphinxをいれたLinuxのrstファイルをWinSCPで編集。
　　(Google日本語入力上で編集したかった)
2.make html
3.SphinxをいれたLinuxにnginxが入ってたので、
　　Sphinxのhtmlのビルド結果を、nginxのlocaltionでalias設定してブラウザで確認。

参考)
Sphinxを使用しているサイト — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
reST構文メモ(Hishidama's Sphinx reStructuredText Memo)