Sphinx on MBP チュートリアル

ちょいと需要があったので、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 %})