sphinxを使ってみる

何やらSphinxなるものを使うと、ドキュメント作成が楽しくなってしまうという噂を聞いたので使ってみたいと思います。

そもそもSphinxというのはPythonで作られていて、reStructuredText(reST)という文法で何か書くと、それをHTMLやpdfに変換してくれるようです。

インストール

環境はUbuntu10.10です。

渋日記:Pythonって何？という人のためのSphinxインストール入門
にある通り、sudo apt-get install python-sphinxだけでいけました！
簡単ですね〜。

下準備

% sphinx-quickstart

このコマンドを実行するといくつか質問が出るので答えます。
（ドキュメントのルートディレクトリや、プロジェクト名等）

答え終わるとこんな感じで生成されます。

% ls
Makefile  _build  _static  _templates  conf.py  index.rst

sphinx-quickstartした時の設問で、ルートドキュメント名は「index」にしておいたので、index.rstがドキュメントの元になります。
（今の時点では_build, _static, _templatesには何もありません）

HTML生成

ドキュメントからHTMLを生成するときは

% make html

とします。
すると_build/htmlの中にHTMLが生成されます。

% ls _build/html
_sources  _static  genindex.html  index.html  objects.inv  search.html  searchindex.js

これのindex.htmlを見てみると・・・


こんな感じのができました。
あとは↓等でマークアップの仕方を覚えれば書けそうです！
reStructuredText入門