このドキュメントにあるのが組み込みのSphinxのビルダーです。 また、 拡張 の仕組みを使うと、ビルダーを追加することもできます。
sphinx-build の起動時には、コマンドラインオプション-bでビルダーの名前を指定しなければなりません。
これは標準的なHTMLビルダーです。 このビルダーはディレクトリにHTMLファイルと、スタイルシート、追加のreSTソースを出力します。 このビルダーにはビルダーの出力を変更できる設定値をいくつか持っています。 詳しくは HTML出力のオプション をご覧ください。
このビルダーの名前は html です。
このクラスは、標準のHTMLビルダーのサブクラスです。これはindex.html という名前のHTMLファイルと一緒にディレクトリを出力します。そのときに、そのページ名がディレクトリの名前になります。例えば、markup/rest.rstというファイルがあるとすると、 markup/rest.htmlというファイルが出力されるのではなく、markup/rest/index.htmlというファイルが出力されます。ページ間のリンクが生成される場合には、末尾のindex.htmlを省いて、 markup/rest/というようなURLが生成されます。
このビルダーの名前はdirhtmlになります。
バージョン 0.6 で追加.
このビルダーは標準のHTMLビルダーと同じものを出力しますが、MicrosoftのHTML Help Workshopで使用できる、HTMLヘルプのサポートファイルも生成します。これらの入力をHTML Help Workshop上でコンパイルすると、CHMファイルが生成されます。
このビルダーの名前はhtmlhelpになります。
このビルダーは標準のHTMLビルダーと同じものを出力しますが、Qt help collectionを使ってコンパイルするのに必要なサポートファイル群も一緒に出力します。
このビルダーの名前はqthelpになります。
このビルダーは標準のHTMLビルダーと同じものを出力しますが、 GNOME Devhelp を使ってコンパイルするのに必要なサポートファイル群も一緒に出力します。これらのファイルはGNOME Devhelp readerを使って見ることができます。
このビルダーの名前はdevhelpになります。
このビルダーは出力フォルダ内に、LaTeXのファイル群を生成します。どのドキュメントを含むかを、 latex_documents の設定値を使って設定します。このビルダーの出力をカスタマイズするための設定値はいくつかあります。詳しくは Options for LaTeX output の章を参照してください。
ノート
生成されるLaTeXファイルは、最低限のTeXディストリビューションいくつかのLaTeXパッケージを使用しています。例えば、TeXLiveでは以下のパッケージをインストールする必要があります。
このビルダーの名前はlatexです。
このビルダーはそれぞれのreSTファイルからテキストファイルを生成します。多くのマークアップが読みやすさのために落とされていますが、ほぼソースのreSTと同じです。
このビルダーの名前はtextです。
バージョン 0.4 で追加.
このビルダーはPythonのシリアライズAPI(pickle, simplejson, phpserialize など)を利用して、実装されています。生成されたHTMLをダンプします。 pickleビルダーはこのクラスのサブクラスになります。
このビルダーのサブクラスを作成して PHP シリアライズ フォーマットでシリアライズするには、以下のようにします:
import phpserialize
class PHPSerializedBuilder(SerializingHTMLBuilder):
name = 'phpserialized'
implementation = phpserialize
out_suffix = '.file.phpdump'
globalcontext_filename = 'globalcontext.phpdump'
searchindex_filename = 'searchindex.phpdump'
出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。
バージョン 0.5 で追加.
このビルダーは、pickleでシリアライズしたほとんどのHTML片と、目次情報を含むディレクトリを作成します。このビルダーで生成した結果は、標準のHTMLテンプレートを使用しない、ウェブアプリケーションや、カスタムの後処理ツールで使用することができます。
出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。
このビルダーの名前は pickle です。以前の名前である web もまだ使用できます。
ファイルのサフィックスは .fpickle になります。グローバルコンテキストは globalcontext.pickle に、検索インデックスは searchindex.pickle になります。
このビルダーは、jsonでシリアライズしたほとんどのHTML片と、目次情報を含むディレクトリを作成します。このビルダーで生成した結果は、標準のHTMLテンプレートを使用しない、ウェブアプリケーションや、カスタムの後処理ツールで使用することができます。
出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。
このビルダーの名前は json です。以前の名前である web もまだ使用できます。
ファイルのサフィックスは .fjson になります。グローバルコンテキストは globalcontext.json に、検索インデックスは searchindex.json になります。
バージョン 0.5 で追加.
このビルダーは、現在の version の設定値と、 versionadded, versionchanged, deprecated の各ディレクティブの情報から、HTMLを生成します。このビルダーは、例えばChangeLogファイルを生成するのに便利です。
このビルダーの名前は changes です。
このビルダーは、すべてのドキュメントの外部リンクをチェックして、 urllib2 を使用してきちんと開けるかどうか確認を行います。壊れたリンク、および、リダイレクトされるリンクの情報を、標準出力と、出力ディレクトリの output.txt というファイルに出力します。
このビルダーの名前は linkcheck です。
組み込みのSphinx拡張には、以下の追加のビルダーが含まれます:
すべてのシリアライズを行うビルダーは、ソースファイル１つごとに対応するファイルと、いくつかの特殊なファイルを出力します。また、reST形式のソースファイルは、出力ディレクトリ内の _sources ディレクトリ内にコピーされます。
PickleHTMLBuilder クラスは組み込みのサブクラスで、pickleでシリアライズを行うインタフェースを実装しています。
ソースファイルごとに出力されるファイルは out_suffix で指定された拡張子を持ち、ソースファイルとおなじようなディレクトリ構成で書き出されます。これらのファイルは以下のようなキーを持つ辞書、あるいは辞書のようなオブジェクトとして復元することが可能です。
出力ディレクトリのルートには、以下の特殊なファイルが配置されます:
pickleでシリアライズされた辞書です。以下のキーを持っています:
ドキュメントの検索で使用されるインデックスになります。以下のエントリーを含む、pickleでシリアライズされたエントリーのリストになります。
ビルド環境です。これは常にpickleでシリアライズされたファイルで、ビルダーとは独立しています。ビルダーが起動された地点で使用された、環境のコピーです。ドキュメント間の共有のメンバーです。
他のシリアライズされたファイルとは異なり、このファイルはSphinxのモジュールだけが中を読むことを想定しています。