イントロダクション

これはSphinxドキュメンテーションビルダーのドキュメントです。Sphinxは一連の reStructuredText (以下reST)のソースファイルを様々な出力形式に変換したり、クロスリファレンスやインデックスなどを自動生成するツールです。これは、もしreSTフォーマットのドキュメント群が含まれるディレクトリがあったとしたら、Sphinxはそこから非常によくまとまった配置のHTMLファイル群を生成することができるということを意味しています。サブディレクトリにソースが分かれていても問題はありません。また、結果のHTMLはブラウザで簡単に見たり、ナビゲーションもしっかりしたものになります。それだけではなく、同じソースファイルから、同様にLaTeXファイルも出力することができ、これをコンパイルすることでPDFバージョンのドキュメントも生成することができます。

このドキュメントでは、自動生成のAPIのドキュメントではなく、手で作成するドキュメンテーションにフォーカスします。そのようなドキュメントのサポートに関してはまだ限定的にはあります(手で作成するコンテンツも自由に追加できるようにする予定)が、もし純粋なAPIドキュメントが必要であれば、 Epydoc をご覧ください。こちらもreSTを解釈することができます。

他のシステムからの変換

このセクションでは、他のドキュメントシステムからreStructuredText/Sphinxへの移行を考えている人達へのヒントを集めています。

• Gerard FlanaganはHTMLからreSTに変換するスクリプトを作成しました。スクリプトは BitBucket 上で見つけることができます。
• 古いPythonのドキュメントをSphinxにコンバートするには、専用のコンバート用のツールを PythonのSVNリポジトリ で見つけることができます。これを使えば、Python-docスタイルのLaTeXのマークアップをSphinx reSTに変換できます。
• Marcin WojdyrはDocbookをreST＋Sphinxマークアップに変換するスクリプトを作成しました。 Google Code にあります。

前提条件

Sphinxの実行には Python 2.4 よりも新しいバージョンのPythonが必要です。もしもソースコードハイライトのサポートが必要であれば、 Pygments ライブラリも一緒にインストールする必要がありますが、 setuptoolsのeasy_installを使用すれば一緒にインストールできます。Sphinxが依存しているコンポーネントとしては、docutilsのバージョン 0.4、もしくはSVNリポジトリのTrunkのスナップショット(壊れていないものに限定)があります。

ドキュメントソースのセットアップ

ドキュメント集のルートディレクトリは ソースディレクトリ と呼ばれます。通常、このディレクトリには、Sphinxのコンフィグファイルの conf.py が含まれますが、違うファイルにあってもかまいません。この場合は、 conf.py が含まれるディレクトリを コンフィギュレーションディレクトリ と呼びます。

バージョン 0.3 で追加: コンフィギュレーションディレクトリを他のディレクトリに設定できるようになりました。

Sphinxを使用するには、まずは sphinx-quickstart と呼ばれるスクリプトを実行して、いくつかの質問に答えて、ソースディレクトリと、デフォルトの conf.py のセットアップを行います。実行するには以下のようにします:

$ sphinx-quickstart

そして、質問に回答していきます。

ビルドの実行

ビルドは、 sphinx-build スクリプトを起動して行います。以下のように実行します。

$ sphinx-build -b latex sourcedir builddir

sourcedir には ソースディレクトリ が、 builddir にはビルドしたドキュメントを置きたいディレクトリ(存在しているディレクトリでなければいけません)を指定します。 -b オプションでビルダーを選択します。このサンプルではSphinxは LaTeXのファイルをビルドします。

The sphinx-build script has several more options:

sphinx-build スクリプトはこれ以外にもいくつかオプションを持っています:

-a

もしこのオプションが設定されると、すべての出力ファイルを書き出します。デフォルトでは新規に作成されたり、変更のあったソースファイルに関連する出力ファイルだけを出力します。このオプションはすべてのビルダーに適応するわけではありません。

-E

保存されている 環境 を使用しないで、完全に再構築する場合に利用します。環境にはクロスリファレンスの構造を保持しています。デフォルトでは新規に作成されたり、最後に実行してから変更のあったソースファイルだけを読み込んで、パースします。

-t タグ

タグ というタグを定義します。これは、タグが設定されているときにだけ内容を取り込むという、 only ディレクティブと関係があります。

バージョン 0.6 で追加.

-d パス

Sphinxは出力ファイルが書き込むことが可能になる前に、すべてのソースファイルを読み込むため、パースされたソースファイルは “doctree pickles”と呼ばれるディレクトリにキャッシュされます。通常は、これらのファイルはビルドディレクトリの下の .doctrees と呼ばれるディレクトリに置かれます。このオプションを指定すると、キャッシュディレクトリを違う場所に設定できます。doctreeはすべてのビルダーで共有されます。

-c パス

ソースディレクトリ以下の conf.py ではなく、オプションで指定されたコンフィグレーションディレクトリ以下の設定ファイルを利用するようにします。ただし、さまざまな他のファイル、パスなど、設定値で与えられたものに関しては、コンフィグレーションディレクトリからの相対パスで探索されることになるため、その状況になってもファイルがきちんと読めるようにしておく必要があります。

バージョン 0.3 で追加.

-C

コンフィグファイルを無視します。設定は -D オプションを使って指定します。

バージョン 0.5 で追加.

-D 設定=値

conf.py に書かれた設定値を上書きで設定します。値は文字列か辞書の値であるひつようがあります。後者の場合には設定名とキーは以下のように設定することができます: -D latex_elements.docclass=scartcl

バージョン 0.6 で変更: 値として辞書の値が使えるようになりました。

-A 名前=値

HTMLテンプレートの中の 名前 を 値 に設定します。

-N

出力に色づけをしないようにします。ただし、Windows上では元々どのような場合にも色を付ける機能は無効になっています。

-q

標準出力に何も出力しないようになります。警告やエラーのみが標準エラー出力に書き出されます。

-Q

標準出力に何も出力しないようになります。警告も抑制されます。エラーのみが標準エラー出力に書き出されます。

-w ファイル

警告とエラーを指定されたファイルに書き出されます。なお、標準エラー出力にも同時に出力されます。

-W

警告をエラーにします。最初の警告でビルドが中断され、 sphinx-build が終了値1を返すようになります。

-P

(Sphinx自体のデバッグをする人用) キャッチされない例外がビルド中に発生したら、Pythonデバッガの pdb を実行します。

コマンドラインオプションでソースディレクトリ、ビルドディレクトリに追加して、1つ以上のファイル名を指定することもできます。Sphinxはこれらのファイルと、それに依存するファイル群だけを出力しようとします。