はじめに
こんにちは、Python界の海老蔵です。去る2010年12月3日にJUS勉強会にてSphinxの紹介をさせていただきました。その時に少々トラブルがあり、ご紹介したかったリンクなどが残念ながら紹介できなかったのでここにリンクや当日のスライドを貼っておきます。
参考
- Overview — Sphinx 1.1.3 documentation
- 本家です。ドキュメントがあります。
- Sphinx-Users.jp :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
- Sphinxをはじめよう :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
- 私がJUS勉強会でご紹介したデモはこちらの抜粋です。
- Overview — Sphinx v1.0.6 documentation
- Sphinx 1.0ドキュメントの日本語訳です。
発表資料
発表に使ったスライドはこちらに置いておきます。
諸々ご紹介
reSTを書くのに適したエディタは?
reSTはただのテキストなのでWindowsのメモ帳でも構いません。ただやはりreST用のハイライトをしてくれるものが良いと思います。EmacsやVimなどでシンタックスハイライトしてくれるのですでに使っている方は拡張の設定をされることをおすすめします。
EmacsでreSTを書く設定は以前こちらのブログでもご紹介しました。
テンプレートの作成
ドキュメントの生成を行う際には複数の形式(HTML, LaTeX, PDF, ePub, manなど)で出力できるわけですが、特にHTMLを生成する例が多いように感じられます。やはり生成するときはある程度カスタマイズしたくなると思いますので、参考になるリンクを紹介します。
- Webサイトを作ろう :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
- カスタムテンプレートの作成方法までを簡単に紹介しています。
- Welcome | Jinja2 (The Python Template Engine)
ドメイン
Sphinxドメインを使うことで、多くの略記を作ることが出来ます。たとえばJUS勉強会のときに清水川さんが紹介していたような議事録に関しても、議事録ドメインを作ることで表記を簡略化することも可能です。
また3rd Partyのドメインも下記のレポジトリにあります。何かドメインが必要だなと思った場合はまずこちらを覗いてみてください。
sdedit (Quick Sequence Diagram Editor)
blockdiag
状態遷移図をテキストで記述してSphinxで図を生成することができます。詳細はこちら。