Builders

These are the built-in Sphinx builders. More builders can be added by extensions.

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.dirhtml.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.singlehtml.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 sphinxcontrib.qthelp.QtHelpBuilder[ソース]

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

バージョン 2.0 で変更: Moved to sphinxcontrib.qthelp from sphinx.builders package.

name = 'qthelp'
format = 'html'
supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']
class sphinxcontrib.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 で追加.

バージョン 2.0 で変更: Moved to sphinxcontrib.applehelp from sphinx.builders package.

class sphinxcontrib.devhelp.DevhelpBuilder[ソース]

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

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

バージョン 2.0 で変更: Moved to sphinxcontrib.devhelp from sphinx.builders package.

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 で変更: Sphinx-1.5より、epub3ビルダーがepubのデフォルトビルダーとして用いられています。

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

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

The produced LaTeX file uses several LaTeX packages that may not be present in a "minimal" TeX distribution installation.

On Ubuntu xenial, the following packages need to be installed for successful PDF builds:

  • texlive-latex-recommended

  • texlive-fonts-recommended

  • texlive-latex-extra

  • latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X for functioning of make latexpdf)

Additional packages are needed in some circumstances (see the discussion of the 'fontpkg' key of latex_elements for more information):

  • to support occasional Cyrillic letters or words, and a fortiori if language is set to a Cyrillic language, the package texlive-lang-cyrillic is required, and, with unmodified 'fontpkg', also cm-super or cm-super-minimal,

  • to support occasional Greek letters or words (in text, not in math directive contents), texlive-lang-greek is required, and, with unmodified 'fontpkg', also cm-super or cm-super-minimal,

  • for 'xelatex' or 'lualatex' (see latex_engine), texlive-xetex resp. texlive-luatex, and, if leaving unchanged 'fontpkg', fonts-freefont-otf.

The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution is based on a TeXLive 2015 snapshot dated March 2016.

バージョン 1.6 で変更: Formerly, testing had been done on Ubuntu precise (TeXLive 2009).

バージョン 2.0 で変更: Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).

注釈

Since 1.6, make latexpdf uses latexmk (not on Windows). This makes sure the needed number of runs is automatically executed to get the cross-references, bookmarks, indices, and tables of contents right.

One can pass to latexmk options via the LATEXMKOPTS Makefile variable. For example:

make latexpdf LATEXMKOPTS="-silent"

reduces console output to a minimum.

Also, if latexmk is at version 4.52b or higher (January 2017) LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in case of numerous graphics inclusions.

To pass options directly to the (pdf|xe|lua)latex binary, use variable LATEXOPTS, for example:

make latexpdf LATEXOPTS="--halt-on-error"
name = 'latex'
format = 'latex'
supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']

Note that a direct PDF builder is being provided by rinohtype. The builder's name is rinoh. Refer to the rinohtype manual for details.

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についての詳細は、 https://www.gnu.org/software/texinfo/ で見ることができます。

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

バージョン 1.1 で追加.

class sphinxcontrib.serializinghtml.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 sphinxcontrib.serializinghtml.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 sphinxcontrib.serializinghtml.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 = '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[ソース]

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

name = 'linkcheck'
format = ''
supported_image_types = []

バージョン 1.5 で変更: Sphinx-1.5より、linkcheck ビルダーは requests モジュールを使用するようになっています。

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 のパッケージのみが中を読むことを想定しています。