S-JIS[2012-04-17] 変更履歴
Sphinxの使用方法のメモ。
|
|
Sphinxのソース（rstファイル）やそこから生成されるファイルは、Sphinxプロジェクト（ディレクトリー）内で管理する。
プロジェクトを作成するには、Windowsの場合、コマンドプロンプトから下記の様なコマンドを実行する。
> cd /d D:\temp > mkdir sphinx > cd sphinx > sphinx-quickstart
途中いくつか入力する項目があるが、以下の項目以外はデフォルト（そのままEnterキーを押す）でOK。
| 確認事項 | 備考 | 入力例 |
|---|---|---|
| Root path for the documentation [.] | ドキュメントのルートディレクトリー。 そのままだとsphinx-quickstartを起動した際のカレントディレクトリーがルートになる。 何か入力すると、そのディレクトリーが作られる。 |
test |
| Separate source and build directories (y/N) [n] | ソースディレクトリーと、生成先ディレクトリーを分けるかどうか。 分けた方が良いので、yにする。 |
y |
| Project name | プロジェクト名。 | sample1 |
| Author name(s) | 著者の名前。 | hishidama |
| Project version | バージョン番号。 | 0.1 |
上記の例だと、「D:\temp\sphinx\test」が作られる。
次いで、作成されたプロジェクトをビルドする。
> cd /d D:\temp\sphinx\test > make html
作成されたプロジェクトディレクトリー直下に（Windows版だと）make.batがあるので、それを実行する。
引数に「html」を付けると、HTMLを生成する。
「build succeeded.」が出ればOK。実行速度はかなり速い。
これで、D:\temp\sphinx\test\buildの下にhtmlというディレクトリーが出来て、その中にindex.html等のHTMLファイルが作られている。
（HTMLファイルなので、ブラウザーから開いて見ることが出来る）
試しにファイルを1つ追加してみる。
「D:\temp\sphinx\test\source」の下に適当なrstファイル（ここでは「test1.rst」とする）を作る。
===== test! ===== これはテストです。
※日本語を入れる場合、UTF-8にする必要がある。
そして、index.rstにこのファイルへのリンクを記述する。
〜
Contents:
.. toctree::
:maxdepth: 2
test1 ←これを追加（rstファイル名の、拡張子抜き）
Indices and tables
==================
〜
再度ビルドしてbuild/html/index.htmlを開くと、test1.htmlへのリンク（「test!」という表記）が出来ているはず。
Sphinxで作られたHTML（ウェブページ）の場合、「Show Source」というメニューが有る場合がある。
これをクリックすると、そのページのrstソースを見ることが出来るので、参考になる。
例： 上記で作ったプロジェクトの場合、左側のサイドメニューの途中に「Show Source」が有る。
例： Asakusa Framework documentationの場合、右側のサイドメニューの一番下に「Show Source」が有る。