Builders¶

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

The builder's "name" must be given to the -M or -b command-line options of sphinx-build to select a builder.

The most common builders are:

html: HTMLページをビルドします。デフォルトのビルダーです。
dirhtml: HTMLページをビルドしますが、ドキュメントごとにディレクトリが生成されます。ウェブサーバで提供する場合に、 .html がURLに付かないようにして、URLが分かりやすくなります。
singlehtml: すべてのコンテンツが含まれる、単一のHTMLを生成します。
htmlhelp, qthelp, devhelp, epub: フォーマットごとに、ドキュメントのコレクションを構築するのに必要な情報と一緒に、HTMLファイルにビルドします。
applehelp: Apple Help Bookを生成します。オープンソースではありませんが、Mac OS X 10.6以降でのみ使用できる hiutil と codesign が必要になります。
latex: pdflatex を使用して、PDFドキュメントにコンパイルできるような、LaTeXのソースにビルドします。
man: UNIX系システムで利用される、groffフォーマットのmanページをビルドします。
texinfo: makeinfo を使ってInfoファイルを生成するための、Texinfoファイルにビルドします。
text: プレーンテキストファイルをビルドします。
gettext: gettextスタイルのメッセージカタログ(.pot ファイル)にビルドします。
doctest: もしも doctest 拡張が有効になっている場合には、ドキュメント内のすべてのdoctestを実行します。
linkcheck: すべての外部リンク先が存在しているか確認をします。
xml: Docutilsが生成するXMLファイルをそのまま出力します。
pseudoxml: コンパクトな整形された"pseudo-XML"を出力します。これは中間ドキュメントツリーの内部構造です。

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

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

name = 'html'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 0.6 で追加.

class sphinx.builders.singlehtml.SingleFileHTMLBuilder[ソース]¶

This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like the root document. No indices will be generated.

name = 'singlehtml'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.0 で追加.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder[ソース]¶

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

name = 'htmlhelp'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinxcontrib.qthelp.QtHelpBuilder[ソース]¶

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

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

name = 'qthelp'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.3 で追加.

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

class sphinxcontrib.devhelp.DevhelpBuilder[ソース]¶

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

name = 'devhelp'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 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'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.4 で追加.

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

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

This builder produces LaTeX source files in the output directory. The actual PDF builds happen inside this output directory and need to be triggered in a second step. This can be done via make all-pdf there. To combine the two steps into only one, use sphinx-build -M (i.e. -M latexpdf not -b latexpdf) or make latexpdf at the project root.

See latex_documents and the chapter LaTeX出力のオプション for available options.

PDF builds need a sufficiently complete LaTeX installation. The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, but PDF builds can be successfully done on much older LaTeX installations.

At any rate, on Ubuntu for example, following packages must all be present:

texlive-latex-recommended
texlive-fonts-recommended
tex-gyre (if latex_engine left to default)
texlive-latex-extra
latexmk

バージョン 4.0.0 で変更: TeX Gyre fonts now required for 'pdflatex' engine (default).

Additional packages are needed in some circumstances:

texlive-lang-cyrillic for Cyrillic (and also then cm-super if using the default fonts),
texlive-lang-greek for Greek (and also then cm-super if using the default fonts),
texlive-xetex if latex_engine is 'xelatex',
texlive-luatex if latex_engine is 'lualatex',
fonts-freefont-otf if latex_engine is either 'xelatex' or 'lualatex'.

注釈

Since 1.6, make latexpdf uses on GNU/Linux and macOS latexmk, as it makes sure the needed number of runs is automatically executed. On Windows the PDF builds execute a fix number of LaTeX runs (three, then makeindex, then two more).

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'¶: The builder's name, for the -b command line option.

format = 'latex'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['application/pdf', 'image/png', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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'¶: The builder's name, for the -b command line option.

format = 'text'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 0.4 で追加.

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

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

name = 'man'¶: The builder's name, for the -b command line option.

format = 'man'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 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'¶: The builder's name, for the -b command line option.

format = 'texinfo'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/jpeg', 'image/gif']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 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'¶

The builder's name, for the -b command line option.

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

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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

class sphinxcontrib.serializinghtml.JSONHTMLBuilder[ソース]¶

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

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

name = 'json'¶: The builder's name, for the -b command line option.

format = 'html'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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

バージョン 0.5 で追加.

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

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

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

name = 'gettext'¶: The builder's name, for the -b command line option.

format = ''¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.1 で追加.

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

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

name = 'changes'¶: The builder's name, for the -b command line option.

format = ''¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinx.builders.dummy.DummyBuilder[ソース]¶

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

name = 'dummy'¶: The builder's name, for the -b command line option.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.4 で追加.

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

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

name = 'linkcheck'¶: The builder's name, for the -b command line option.

format = ''¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.5 で変更: Since Sphinx 1.5, the linkcheck builder uses the requests module.

バージョン 3.4 で変更: The linkcheck builder retries links when servers apply rate limits.

class sphinx.builders.xml.XMLBuilder[ソース]¶

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

name = 'xml'¶: The builder's name, for the -b command line option.

format = 'xml'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.2 で追加.

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

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

name = 'pseudoxml'¶: The builder's name, for the -b command line option.

format = 'pseudoxml'¶: The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

バージョン 1.2 で追加.

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

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

すべてのシリアライズを行うビルダーは、ソースファイル１つごとに対応するファイルと、いくつかの特殊なファイルを出力します。また、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の場合には、関連のリストが含まれますが、prevとnextの場合には関連が一つだけ含まれます。
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 のパッケージのみが中を読むことを想定しています。

On this page

Site navigation

Builders¶

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