このドキュメントにあるのが組み込みの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になります。
New in version 0.6.
これは、プロジェクト全体のファイルを結合して、1ファイルにして出力するHTMLビルダーです。 (これは小さなプロジェクトでうまく動作します。) このファイルは、マスタードキュメントに似た名前になります。 また、索引は生成されません。
このビルダーの名前は singlehtml になります。
New in version 1.0.
このビルダーは標準のHTMLビルダーと同じものを出力しますが、MicrosoftのHTML Help Workshopで使用できる、HTMLヘルプのサポートファイルも生成します。これらの入力をHTML Help Workshop上でコンパイルすると、CHMファイルが生成されます。
このビルダーの名前はhtmlhelpになります。
このビルダーは標準のHTMLビルダーと同じものを出力しますが、 Qt help collectionを使ってコンパイルするのに必要なサポートファイル群も一緒に出力します。
このビルダーの名前はqthelpになります。
このビルダーは標準のHTMLビルダーと同じものを出力しますが、 GNOME Devhelp を使ってコンパイルするのに必要なサポートファイル群も一緒に出力します。これらのファイルはGNOME Devhelp readerを使って見ることができます。
このビルダーの名前はdevhelpになります。
このビルダーはstandaloneのHTMLビルダーと同じものを出力しますが、電子ブックリーダーのための、 epub ファイルも一緒に生成します。詳しくは Epub情報 を参照してください。epubフォーマットの定義については http://www.idpf.org/specs.htm もしくは http://en.wikipedia.org/wiki/EPUB を参照してください。
電子ブックリーダーによっては、参照のリンクターゲットが表示されない場合があります。そのため、必要に応じて、このビルダーはリンクの後ろにターゲットを追加します。URLの表示は、 link-target クラスをCSSのルールに追加することで、カスタマイズすることができます。
このビルダーの名前はepubになります。
このビルダーは出力フォルダ内に、LaTeXのファイル群を生成します。どのドキュメントを含むかを、 latex_documents の設定値を使って設定します。このビルダーの出力をカスタマイズするための設定値はいくつかあります。詳しくは LaTeX出力のオプション の章を参照してください。
Note
生成されるLaTeXファイルは、最低限のTeXディストリビューションいくつかのLaTeXパッケージを使用しています。例えば、TeXLiveでは以下のパッケージをインストールする必要があります。
このビルダーの名前はlatexです。
rst2pdf のバージョン 0.12以降を使うと、ReportLabを使用して、PDFを直接出力するビルダーが利用できます。これを使用するためには、 extensions に 'rst2pdf.pdfbuilder' を追加して、ビルダー名 pdf を指定してビルドします。詳しくは、 rst2pdfのマニュアル を参照してください。
このビルダーはそれぞれのreSTファイルからテキストファイルを生成します。多くのマークアップが読みやすさのために落とされていますが、ほぼソースのreSTと同じです。
このビルダーの名前はtextです。
New in version 0.4.
このビルダーは、groffフォーマットのmanページを作成します。manページに含めるドキュメントは、 man_pages 設定値を使って指定します。
このビルダーの名前は man になります。
Note
このビルダーを実行するには、docutilsのmanページライターが必要になるため、 docutils 0.6以降が必要となります。
New in version 1.0.
このビルダーは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'
pickleモジュールと同じ名前の dump(), load(), dumps(), loads() 関数が実装されているモジュールです。このようなインタフェースを実装しているモジュールでよく知られているものには、 simplejson (Python2.6では json), phpserialize, plistlib などがあります。
すべての通常のファイルに付くサフィックスです。
“グローバルコンテキスト”を含むファイルのファイル名です。これは、プロジェクト名などの一般的な設定値を含む辞書です。
Sphinxが作成する、検索インデックスのファイル名です。
出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。
New in version 0.5.
このビルダーは、pickleでシリアライズしたほとんどのHTML片と、目次情報を含むディレクトリを作成します。このビルダーで生成した結果は、標準のHTMLテンプレートを使用しない、ウェブアプリケーションや、カスタムの後処理ツールで使用することができます。
出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。
このビルダーの名前は pickle です。以前の名前である web もまだ使用できます。
ファイルのサフィックスは .fpickle になります。グローバルコンテキストは globalcontext.pickle に、検索インデックスは searchindex.pickle になります。
このビルダーは、jsonでシリアライズしたほとんどのHTML片と、目次情報を含むディレクトリを作成します。このビルダーで生成した結果は、標準のHTMLテンプレートを使用しない、ウェブアプリケーションや、カスタムの後処理ツールで使用することができます。
出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。
このビルダーの名前は json です。
ファイルのサフィックスは .fjson になります。グローバルコンテキストは globalcontext.json に、検索インデックスは searchindex.json になります。
New in version 0.5.
このビルダーは、現在の version の設定値と、 versionadded, versionchanged, deprecated の各ディレクティブの情報から、HTMLを生成します。このビルダーは、例えばChangeLogファイルを生成するのに便利です。
このビルダーの名前は changes です。
このビルダーは、すべてのドキュメントの外部リンクをチェックして、 urllib2 を使用してきちんと開けるかどうか確認を行います。壊れたリンク、および、リダイレクトされるリンクの情報を、標準出力と、出力ディレクトリの output.txt というファイルに出力します。
このビルダーの名前は linkcheck です。
組み込みのSphinx拡張には、以下の追加のビルダーが含まれます:
すべてのシリアライズを行うビルダーは、ソースファイル１つごとに対応するファイルと、いくつかの特殊なファイルを出力します。また、reST形式のソースファイルは、出力ディレクトリ内の _sources ディレクトリ内にコピーされます。
PickleHTMLBuilder クラスは組み込みのサブクラスで、pickleでシリアライズを行うインタフェースを実装しています。
ソースファイルごとに出力されるファイルは out_suffix で指定された拡張子を持ち、ソースファイルと同様のディレクトリ構成で書き出されます。これらのファイルは以下のようなキーを持つ辞書、あるいは辞書のようなオブジェクトとして復元することが可能です。
出力ディレクトリのルートには、以下の特殊なファイルが配置されます:
pickleでシリアライズされた辞書です。以下のキーを持っています:
ドキュメントの検索で使用されるインデックスになります。以下のエントリーを含む、pickleでシリアライズされたエントリーのリストになります。
ビルド環境です。これは常にpickleでシリアライズされたファイルで、ビルダーとは独立しています。ビルダーが起動された地点で使用された、環境のコピーです。ドキュメント間の共有のメンバーです。
Todo
共通メンバーのドキュメントを書く
他のシリアライズされたファイルとは異なり、このファイルは Sphinx のパッケージのみが中を読むことを想定しています。