ちょいと需要があったので、Sphinx を使ったことのない人が MacBookPro に Sphinx 環境を構築してとりあえずドキュメントをビルドできるまでのチュートリアルを書きました。 Sphinx 公式にチュートリアルがあるけどこちらは自分が知りたかったことだけにフォーカスしてみました。
ちなみに自分も Sphinx 初心者なので知らないことたくさんあるけどちょっとしたドキュメントならすぐ作れるようになりました。いいですね、Sphinx。
インストール
OSX には最初から python が入っているので easy_install すればよいです。 諸事情で新規にインストールする場合は
% brew install python
% ln -s /usr/local/share/python/easy_install /usr/local/bin/easy_install
% ln -s /usr/local/share/python/easy_install-2.7 /usr/local/bin/easy_install-2.7
% rehash
続いて easy_install で sphinx をインストールします。
% easy_install -U Sphinx
% ln -s /usr/local/share/python/sphinx-apidoc /usr/local/bin/sphinx-apidoc
% ln -s /usr/local/share/python/sphinx-autogen /usr/local/bin/sphinx-autogen
% ln -s /usr/local/share/python/sphinx-build /usr/local/bin/sphinx-build
% ln -s /usr/local/share/python/sphinx-quickstart /usr/local/bin/sphinx-quickstart
% rehash
最初のステップ
sphinx-quickstart にドキュメントディレクトリのパスをつけて起動します
% sphinx-quickstart hello-sphinx
sphinx-quickstart の質問には基本デフォルト (enter) で良いです。以下の箇所だけ入力が必要です。
Project name: プロジェクト名。Hello Sphinx とか
Author name(s): 名前
Project version: 1.0 でいいんじゃない?
質問全部に答えるとファイルがいくつか作成されます。 index.rst が最初に編集するファイルです。 参考: http://sphinx.pocoo.org/tutorial.html#setting-up-the-documentation-sources
ファイルの追加
index.rst を編集してもちろん良いけど基本インデックスなので、そこそこの内容を書きたい場合はファイルを追加するのが良いでしょう。拡張子 .rst でファイルを追加して拡張子抜きの名前を index.rst の toctree に追加します。 hello.rst を追加する例
Contents:
.. toctree::
:maxdepth: 2
hello
参考: http://sphinx.pocoo.org/tutorial.html#defining-document-structure
ビルド
% make html
で生成されます。 _build/html/index.html を見るとよいです。
あとは
reST の書き方参考にしてざくざく書いてみてください。
参考: http://sphinx.pocoo.org/rest.html
おまけ: 見栄えをかっこよくする
[Twitter Bootstrap をテーマとして適用する方法]({% post_url 2012-01-10-sphinx-with-twitter-bootstrap %})