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以降でのみ使用できる hiutilcodesign が必要になります。

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[ソース]

This builder produces the same output as the standalone HTML builder, but also generates an epub file for ebook readers. See Epub情報 for details about it. For definition of the epub format, have a look at https://idpf.org/epub or https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3 files.

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[ソース]

This builder uses a module that implements the Python serialization API (pickle, simplejson, phpserialize, and others) to dump the generated HTML documentation. The pickle builder is a subclass of it.

このビルダーのサブクラスを作成して PHP シリアライズ フォーマットでシリアライズするには、以下のようにします:

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'
implementation

A module that implements dump(), load(), dumps() and loads() functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are simplejson, phpserialize, plistlib, and others.

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[ソース]

This builder produces an HTML overview of all versionadded, versionchanged, deprecated and versionremoved directives for the current version. This is useful to generate a changelog file, for example.

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拡張には、以下の追加のビルダーが含まれます:

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

すべてのシリアライズを行うビルダーは、ソースファイル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 のパッケージのみが中を読むことを想定しています。