利用可能なビルダー

このドキュメントにあるのが組み込みのSphinxのビルダーです。 また、 拡張 の仕組みを使うと、ビルダーの追加もできます。

sphinx-build の起動時には、コマンドラインオプション-bでビルダーの名前を指定しなければなりません。

class sphinx.builders.html.StandaloneHTMLBuilder[ソース]

これは標準的なHTMLビルダーです。 このビルダーはディレクトリにHTMLファイルと、スタイルシートを出力します。reSTソースの出力も指定できます。 このビルダーにはビルダーの出力を変更できる設定値をいくつか持っています。 詳しくは HTML出力のオプション をご覧ください。

name = 'html'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']
class sphinx.builders.html.DirectoryHTMLBuilder[ソース]

このクラスは、標準のHTMLビルダーのサブクラスです。これはindex.html という名前のHTMLファイルと一緒にディレクトリを出力します。そのときに、そのページ名がディレクトリの名前になります。例えば、markup/rest.rstというファイルがあるとすると、 markup/rest.htmlというファイルが出力されるのではなく、markup/rest/index.htmlというファイルが出力されます。ページ間のリンクが生成される場合には、末尾のindex.htmlを省いて、 markup/rest/というようなURLが生成されます。

name = 'dirhtml'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

バージョン 0.6 で追加.

class sphinx.builders.html.SingleFileHTMLBuilder[ソース]

これは、プロジェクト全体のファイルを結合して、1ファイルにして出力するHTMLビルダーです。 (これは小さなプロジェクトでうまく動作します。) このファイルは、マスタードキュメントに似た名前になります。 また、索引は生成されません。

name = 'singlehtml'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

バージョン 1.0 で追加.

class sphinx.builders.htmlhelp.HTMLHelpBuilder[ソース]

このビルダーは標準のHTMLビルダーと同じものを出力しますが、MicrosoftのHTML Help Workshopで使用できる、HTMLヘルプのサポートファイルも生成します。これらの入力をHTML Help Workshop上でコンパイルすると、CHMファイルが生成されます。

name = 'htmlhelp'
format = 'html'
supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
class sphinx.builders.qthelp.QtHelpBuilder[ソース]

このビルダーは標準のHTMLビルダーと同じものを出力しますが、 Qt help collectionを使ってコンパイルするのに必要なサポートファイル群も一緒に出力します。

name = 'qthelp'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']
class sphinx.builders.applehelp.AppleHelpBuilder[ソース]

このビルダーはApple Help Bookを出力します。standalone HTMLビルダーと同じ出力を元に生成しています。

ソースディレクトリが何らかの``.lproj``フォルダを含む場合、選択された言語に対応するフォルダが、生成された出力とマージされます。これらのフォルダは、その他のドキュメントタイプには無視されます。

有効なヘルプブックを生成するには、コマンドラインツールの:program:hiutil`をビルダーに用意してやる必要があります。ただ、Mac OS X 10.6 and aboveのみでしか使用できません。インデックス作成のステップを飛ばすには:confval:`applehelp_disable_external_tools`に`True``を設定します。この場合、:program:`hiutil`をバンドル内の全ての`.lproj``フォルダに対して実行する必要があります。

name = 'applehelp'
format = 'html'
supported_image_types = ['image/png', 'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']

バージョン 1.3 で追加.

class sphinx.builders.devhelp.DevhelpBuilder[ソース]

このビルダーは標準のHTMLビルダーと同じものを出力しますが、GNOME Devhelpリーダーで使用されいてる GNOME Devhelp のサポートファイルも生成します。

name = 'devhelp'
format = 'html'
supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
class sphinx.builders.epub.EpubBuilder[ソース]

このビルダーは標準のStandaloneHTMLBuilderと同じものを出力しますが、電子ブックリーダーのための、 epub ファイルも一緒に生成します。詳しくは Epub情報 を参照してください。epubフォーマットの定義については http://idpf.org/epub もしくは https://en.wikipedia.org/wiki/EPUB を参照してください。このビルダーが生成するファイルは EPUB 2 です。

name = 'epub2'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

バージョン 1.5 で撤廃: Since Sphinx-1.5, the epub3 builder is used for the default builder of epub. Now EpubBuilder is renamed to epub2.

class sphinx.builders.epub3.Epub3Builder[ソース]

このビルダーは標準のStandaloneHTMLBuilderと同じものを出力しますが、電子ブックリーダーのための、 epub ファイルも一緒に生成します。詳しくは Epub情報 を参照してください。epubフォーマットの定義については http://idpf.org/epub もしくは https://en.wikipedia.org/wiki/EPUB を参照してください。このビルダーが生成するファイルは EPUB 3 です。

name = 'epub'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

バージョン 1.4 で追加.

バージョン 1.5 で変更: Since Sphinx-1.5, the epub3 builder is used for the default builder of epub.

class sphinx.builders.latex.LaTeXBuilder[ソース]

このビルダーは出力フォルダ内に、LaTeXのファイル群を生成します。どのドキュメントを含むかを、 latex_documents の設定値を使って設定します。このビルダーの出力をカスタマイズするための設定値がいくつかあります。詳しくは LaTeX出力のオプション の章を参照してください。

注釈

生成されるLaTeXファイルは、最低限のTeXディストリビューションと、そのほかにいくつかのLaTeXパッケージを使用しています。例えば、TeXLiveでは以下のパッケージをインストールする必要があります。

  • latex-recommended
  • latex-extra
  • fonts-recommended
name = 'latex'
format = 'latex'
supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']

ReportLab を使った直接PDFを生成するビルダーは rst2pdf のバージョン0.12以上で使用できることに気をつけてください。使用するには 'rst2pdf.pdfbuilder'extensions に加えてください。また、その名前は pdf となります。詳細は rst2pdf manual を参照してください。

class sphinx.builders.text.TextBuilder[ソース]

このビルダーはそれぞれのreSTファイルからテキストファイルを生成します。ほぼreSTのソースと同じですが、多くのマークアップが読みやすさのために落とされています。

name = 'text'
format = 'text'
supported_image_types = []

バージョン 0.4 で追加.

class sphinx.builders.manpage.ManualPageBuilder[ソース]

このビルダーは、groffフォーマットのmanページを作成します。manページに含めるドキュメントは、 man_pages 設定値を使って指定します。

name = 'man'
format = 'man'
supported_image_types = []

バージョン 1.0 で追加.

class sphinx.builders.texinfo.TexinfoBuilder[ソース]

このビルダーは、 makeinfo プログラムを使って、Infoファイルを生成可能な、Texinfoファイルを生成します。どのドキュメントをTexinfoファイルに含めるかは、 texinfo_documents 設定値を使って設定します。

InfoフォーマットはGNU Emacsやターミナルベースの info プログラムで使用される、オンラインヘルプシステムの基盤となっています。詳しくは、 Texinfo情報 を参照してください。Texinfoフォーマットは、GNUプロジェクトの、公式なドキュメントシステムです。Texinfoについての詳細は、 http://www.gnu.org/software/texinfo/ で見ることができます。

name = 'texinfo'
format = 'texinfo'
supported_image_types = ['image/png', 'image/jpeg', 'image/gif']

バージョン 1.1 で追加.

class sphinx.builders.html.SerializingHTMLBuilder[ソース]

このビルダーは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'
implementation

pickleモジュールと同じ名前の dump(), load(), dumps(), loads() 関数が実装されているモジュールです。このようなインタフェースを実装しているモジュールでよく知られているものには、 simplejson, phpserialize, plistlib などがあります。

out_suffix

すべての通常のファイルに付くサフィックスです。

globalcontext_filename

“グローバルコンテキスト”を含むファイルのファイル名です。これは、プロジェクト名などの一般的な設定値を含む辞書です。

searchindex_filename

Sphinxが作成する、検索インデックスのファイル名です。

出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。

バージョン 0.5 で追加.

class sphinx.builders.html.PickleHTMLBuilder[ソース]

このビルダーは、pickleでシリアライズしたほとんどのHTML片と、目次情報を含むディレクトリを作成します。このビルダーで生成した結果は、標準のHTMLテンプレートを使用しない、ウェブアプリケーションや、カスタムの後処理ツールで使えます。

出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。

name = 'pickle'

古いビルダー名 web もまだ使用できます。

format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

ファイルのサフィックスは .fpickle になります。グローバルコンテキストは globalcontext.pickle に、検索インデックスは searchindex.pickle になります。

class sphinx.builders.html.JSONHTMLBuilder[ソース]

このビルダーは、jsonでシリアライズしたほとんどのHTML片と、目次情報を含むディレクトリを作成します。このビルダーで生成した結果は、標準のHTMLテンプレートを使用しない、ウェブアプリケーションや、カスタムの後処理ツールで使用できます。

出力フォーマットの詳細については、 シリアライズを行うビルダーの詳細 を参照してください。

name = 'json'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

ファイルのサフィックスは .fjson になります。グローバルコンテキストは globalcontext.json に、検索インデックスは searchindex.json になります。

バージョン 0.5 で追加.

class sphinx.builders.gettext.MessageCatalogBuilder[ソース]

このビルダーは、gettext スタイルのメッセージ カタログを生成します。最上位のファイルとサブディレクトリはそれぞれ1つの .pot カタログ テンプレートに変換されます。

この機能については、 国際化 のドキュメントを参照してください。

name = u'gettext'
format = ''
supported_image_types = []

バージョン 1.1 で追加.

class sphinx.builders.changes.ChangesBuilder[ソース]

このビルダーは、現在の version の設定値と、 versionadded, versionchanged, deprecated の各ディレクティブの情報から、HTMLを生成します。このビルダーは、例えばChangeLogファイルを生成するのに便利です。

name = 'changes'
format = ''
supported_image_types = []
class sphinx.builders.dummy.DummyBuilder[ソース]

このビルダーは何も出力を行いません。入力ファイルをパースしその整合性を確認するだけです。これは入力ファイルの文法をチェックする場合有用です。

name = 'dummy'
supported_image_types = []

バージョン 1.4 で追加.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder[ソース]

このビルダーは、すべてのドキュメントの外部リンクをチェックして、 urllib2 を使用してきちんと開けるかどうか確認を行います。壊れたリンク、および、リダイレクトされるリンクの情報を、標準出力と、出力ディレクトリの output.txt というファイルに出力します。

name = 'linkcheck'
format = ''
supported_image_types = []
class sphinx.builders.xml.XMLBuilder[ソース]

このビルダーは、Docutils ネイティブのXML ファイルを生成します。出力されたファイルはXSLTプロセッサなどの標準的なXMLツールで任意の最終的なフォーマットに変換できます。

name = 'xml'
format = 'xml'
supported_image_types = []

バージョン 1.2 で追加.

class sphinx.builders.xml.PseudoXMLBuilder[ソース]

このビルダーは、Sphinx/Docutilsの「読み込み(Reader)・変換(Transform)・書き出し(Writer)」パイプラインのデバッグに使うことが出来ます。このビルダーは入れ子構造で(終了タグ)のないコンパクトな”擬似XML”ファイルを生成します。全てのエレメントの外部属性が出力され、また残りの「保留中」の要素の内部属性も出力されます。

name = 'pseudoxml'
format = 'pseudoxml'
supported_image_types = []

バージョン 1.2 で追加.

組み込みのSphinx拡張には、以下の追加のビルダーが含まれます:

シリアライズを行うビルダーの詳細

すべてのシリアライズを行うビルダーは、ソースファイル1つごとに対応するファイルと、いくつかの特殊なファイルを出力します。また、reST形式のソースファイルは、出力ディレクトリ内の _sources ディレクトリ内にコピーされます。

PickleHTMLBuilder クラスは組み込みのサブクラスで、pickleでシリアライズを行うインタフェースを実装しています。

ソースファイルごとに出力されるファイルは out_suffix で指定された拡張子を持ち、ソースファイルと同様のディレクトリ構成で書き出されます。これらのファイルは以下のようなキーを持つ辞書、あるいは辞書のようなオブジェクトとして復元することが可能です。

body

HTMLの本体が格納されています。HTMLトランスレータを利用してレンダリングされたものになります。

title

ドキュメントのタイトルです。HTMLのマークアップが含まれている可能性があります。

toc

ファイルの索引になります。HTMLの <ul> を使って表現されています。

display_toc

toc が一つ以上のエントリーを含む場合に True になる、ブール型の値になります。

current_page_name

現在のファイルのドキュメント名になります。

parents, prev and next

TOCツリー上で関連する章の情報です。関連は辞書として表現されます。 link(HREF情報)とtitle(関連ドキュメントのタイトル情報のHTML)が含まれます。 parentsの場合には、関連のリストが含まれますが、prevnextの場合には関連が一つだけ含まれます。

sourcename

_sources以下に置かれている、ソースファイルの名前になります。

出力ディレクトリのルートには、以下の特殊なファイルが配置されます:

SerializingHTMLBuilder.globalcontext_filename

pickleでシリアライズされた辞書です。以下のキーを持っています:

project, copyright, release, version

設定ファイルで指定された、同じ名前の設定の値が入ります。

style

html_style

last_updated

最後にビルドした日時です。

builder

使用したビルダーの名前です。この場合はこれは常に'pickle'になります。

titles

すべてのドキュメントのHTML形式のタイトルを含む辞書です。

SerializingHTMLBuilder.searchindex_filename

ドキュメントの検索で使用されるインデックスになります。以下のエントリーを含む、pickleでシリアライズされたエントリーのリストになります。

  • インデックスが作成されたドキュメント名のリストです。

  • HTMLの文字列形式で作成された、タイトルのリストです。最初のリストと同じ順序になっています。

  • 単語から、数値のリストへの辞書です。この数値は最初のリストのインデックスになります。

environment.pickle

ビルド環境です。これは常にpickleでシリアライズされたファイルで、ビルダーとは独立しています。ビルダーが起動された地点で使用された、環境のコピーです。ドキュメント間の共有のメンバーです。

課題

共通メンバーのドキュメントを書く

他のシリアライズされたファイルとは異なり、このファイルは sphinx のパッケージのみが中を読むことを想定しています。