設定

設定ディレクトリ には必ず conf.py が含まれています。このファイルは "ビルド設定ファイル" と呼ばれていて、Sphinxの入出力の動作をカスタマイズするのに必要な（ほとんど）すべての設定はこのファイルに含まれています。この設定ファイルはPythonのプログラムとして書かれています。

An optional file docutils.conf can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.

設定ファイルは、ビルド時にPythonコードとして実行される(設定ファイルが含まれる フォルダをカレントディレクトリに設定し、 execfile() を使用して呼び出される)ので、任意の複雑なコードを記述できます。Sphinxが読み込む際には単純にファイルの 中の名前空間に定義されている名前を使うことで、設定を読み込みます。

詳細に説明するにあたっての注意点を列挙します。

  • 特別に指定されていない場合には、設定値は文字列型になります。また、指定されていない場合のデフォルト値は空文字列です。

  • "完全限定名(FQN)"という用語は、モジュール内のインポート可能なPythonオブジェクトをあらわす名前です。例えば、 "sphinx.builders.Builder" という完全限定名は、 sphinx.builders モジュールにある Builder クラスを意味します。

  • ドキュメント名は、パスのセパレータとして / を使用します。また、拡張子は含まないで表記します。

  • Since conf.py is read as a Python file, the usual rules apply for encodings and Unicode support.

  • 設定の名前空間の内容はpickle化されます(そのため、Sphinxは設定の変更されたのを確認できます)。そのため、pickle化できない値が含まれているのを発見したら、 del を使って名前空間から削除します。モジュールは自動的に削除されるため、 import したモジュールがあったら、使用後に del を行う必要はありません。

  • 設定ファイルには、 tags という名前の特別なオブジェクトがあります。これはタグの問い合わせをしたり、変更するのに使用します(詳しくは タグを使用したインクルード も参照)。問い合わせには tags.has('tag') 、変更には tags.add('tag') 、 tags.remove('tag') という使い方をします。コマンドラインオプション -t を用いて設定されたタグ、もしくは tags.add('tag') を用いて設定されたタグのみが tags.has('tag') を用いてタグの問合せが可能です。ビルダーが初期化された 後に 作成されるため、現在のビルダーのタグは conf.py には出てこないことに注意してください。

プロジェクト情報

project

ドキュメントを書いているプロジェクト名です。

author

The author name(s) of the document. The default value is 'unknown'.

'2008, Author Name' という形式の著作権表記です。

An alias of copyright.

バージョン 3.5 で追加.

version

主要なプロジェクトのバージョンです。 置換構文を使って |version| このように書きます。例えば、Pythonのドキュメントであれば、これは 2.6 になります。

release

完全なプロジェクトのバージョンです。置換構文を使って |release| このように使用するか、あるいはHTMLテンプレートの中の変数として使用されます。例えば、Pythonのドキュメントの場合には、 2.6.0rc1 のような文字列になります。

version と release を分けて設定する必要がなければ、同じ文字列を入れてください。

一般的な設定

extensions

A list of strings that are module names of extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.

もし拡張機能が他のディレクトリにある場合には、confファイルの中で sys.path にパスを追加することで、使用できるようになります。注意すべき点としては、絶対パスを指定しなければならない点です。もし、 設定ディレクトリ からの相対パスが分かっている場合には、 os.path.abspath() を以下のように使用します:

import sys, os

sys.path.append(os.path.abspath('sphinxext'))

extensions = ['extname']

上記のコードでは sphinxext というサブディレクトリに含まれる extname という名前の拡張機能をロードしています。

設定ファイル自身で拡張機能を実装してもかいません。その場合には、 setup() という名前の関数を提供する必要があります。

source_suffix

The file extensions of source files. Sphinx considers the files with this suffix as sources. The value can be a dictionary mapping file extensions to file types. For example:

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

By default, Sphinx only supports 'restructuredtext' file type. You can add a new file type using source parser extensions. Please read a document of the extension to know which file type the extension supports.

The value may also be a list of file extensions: then Sphinx will consider that they all map to the 'restructuredtext' file type.

Default is {'.rst': 'restructuredtext'}.

注釈

file extensions have to start with a dot (e.g. .rst).

バージョン 1.3 で変更: 複数の拡張子をリストで指定出来ます。

バージョン 1.8 で変更: Support file type mapping

source_encoding

すべてのreSTのソースファイルのエンコーディングを指定します。デフォルトかつ、推奨のエンコーディングは 'utf-8-sig' です。

バージョン 0.5 で追加: 以前はSphinxはUTF-8エンコードのソースのみ受け付けていました。

source_parsers

必要により、ソースファイルの拡張子に対応するパーサークラスの辞書を指定します。辞書キーには拡張子、値にはパーサークラスあるいはその完全限定名(FQN)が入ります。パーサークラスは docutils.parsers.Parser または sphinx.parsers.Parser という形式になります。この辞書にない拡張子のファイルに対しては、デフォルトのreStructuredTextパーサーが適用されます。

例えば:

source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}

注釈

Refer to Markdown for more information on using Markdown with Sphinx.

バージョン 1.3 で追加.

バージョン 1.8 で非推奨: Now Sphinx provides an API Sphinx.add_source_parser() to register a source parser. Please use it instead.

master_doc

Same as root_doc.

バージョン 4.0 で変更: Renamed master_doc to root_doc.

root_doc

The document name of the "root" document, that is, the document that contains the root toctree directive. Default is 'index'.

バージョン 2.0 で変更: The default is changed to 'index' from 'contents'.

バージョン 4.0 で変更: Renamed root_doc from master_doc.

exclude_patterns

globスタイルのパターンのリストを設定し、ソースファイルの探索時に排除すべきファイルを指定します。 1 これらのパターンは、ソースディレクトリからの相対パスで渡されるソースファイル名に対してマッチします。すべての環境で、ディレクトリの指定として、スラッシュ(/)が使用されます。

サンプルのパターン:

  • 'library/xml.rst' -- library/xml.rst ファイルを無視します。 unused_docs のエントリーの置き換えになります。

  • 'library/xml' -- ignores the library/xml directory

  • 'library/xml*' -- library/xml から始まる全てのファイルとディレクトリを無視します。

  • '**/.svn' -- ignores all .svn directories

exclude_patterns は、 html_static_path 及び html_extra_path の中の静的ファイルを探索する時にも参照されます。

バージョン 1.0 で追加.

templates_path

追加のテンプレート(もしくは組み込みのテーマに関するテンプレートをオーバーライトするテンプレート)が含まれているパスのリストです。 設定ディレクトリからの相対パスで設定します。

バージョン 1.3 で変更: これらのファイルは自動的に exclude_patterns に追加され、ビルドの対象にはなりません。

template_bridge

A string with the fully-qualified name of a callable (or simply a class) that returns an instance of TemplateBridge. This instance is then used to render HTML documents, and possibly the output of other builders (currently the changes builder). (Note that the template bridge must be made theme-aware if HTML themes are to be used.)

rst_epilog

A string of reStructuredText that will be included at the end of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_prolog). An example:

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

バージョン 0.6 で追加.

rst_prolog

A string of reStructuredText that will be included at the beginning of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_epilog). An example:

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""

バージョン 1.0 で追加.

primary_domain

The name of the default domain. Can also be None to disable a default domain. The default is 'py'. Those objects in other domains (whether the domain name is given explicitly, or selected by a default-domain directive) will have the domain name explicitly prepended when named (e.g., when the default domain is C, Python functions will be named "Python function", not just "function").

バージョン 1.0 で追加.

default_role

デフォルトロールとして使用する、reSTロールの名前(組み込み、もしくはSphinx拡張)を設定します。これは `このような` テキストのマークアップに対して適用されます。これは 'py:obj' というものがあれば、 `filter` という関数と、Pythonの "filter" のクロスリファレンスを行います。デフォルトは None で、デフォルトのロールは適用されません。

デフォルトのロールは、reST標準の default-role ディレクティブを使用することによっても個々のドキュメントに対して設定できます。

バージョン 0.4 で追加.

keep_warnings

If true, keep warnings as "system message" paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when sphinx-build is run.

デフォルトは False で 0.5以前の振る舞いを維持するにはこのままにしてください。

バージョン 0.5 で追加.

suppress_warnings

任意の警告メッセージを抑制するときに使う警告の種類のリスト。

Sphinxは以下の警告の種類をサポートしています:

  • app.add_node

  • app.add_directive

  • app.add_role

  • app.add_generic_role

  • app.add_source_parser

  • download.not_readable

  • image.not_readable

  • ref.term

  • ref.ref

  • ref.numref

  • ref.keyword

  • ref.option

  • ref.citation

  • ref.footnote

  • ref.doc

  • ref.python

  • misc.highlighting_failure

  • toc.circular

  • toc.secnum

  • epub.unknown_project_files

  • epub.duplicated_toc_entry

  • autosectionlabel.*

これらの種類から選択できます。

現状、このオプションが 実験的 な機能であることに注意して下さい。

バージョン 1.4 で追加.

バージョン 1.5 で変更: misc.highlighting_failure　を追加

バージョン 1.5.1 で変更: Added epub.unknown_project_files

バージョン 1.6 で変更: Added ref.footnote

バージョン 2.1 で変更: Added autosectionlabel.*

バージョン 3.3.0 で変更: Added epub.duplicated_toc_entry

needs_sphinx

ドキュメントが想定しているSphinxのバージョンを設定します。 '1.1' というような形式で、 メジャー.マイナー というバージョン文字列を設定すると、Sphinxは自分のバージョンとの比較を行い、もしもバージョンが古すぎる場合にはビルドを中止します。デフォルトでは、チェックをしないようになっています。

バージョン 1.0 で追加.

バージョン 1.4 で変更: マイクロバージョンの文字列も受け取れます。

needs_extensions

この値は extensions で指定したSphinx拡張に対してバージョン指定する辞書型の値です。例えば needs_extensions = {'sphinxcontrib.something': '1.5'} のような形です。このバージョン文字列は major.minor 型で指定してください。バージョン指定は全ての拡張に指定する必要はなく、チェックしたいものに対してのみ指定できます。

この機能を使うにはSphinx拡張が自分自身のバージョンをSphinxに対し引き渡している必要があります。(設定方法は以下を参考にして下さい Sphinx拡張機能の開発).

バージョン 1.3 で追加.

manpages_url

A URL to cross-reference manpage directives. If this is defined to https://manpages.debian.org/{path}, the :manpage:`man(1)` role will link to <https://manpages.debian.org/man(1)>. The patterns available are:

  • page - the manual page (man)

  • section - the manual section (1)

  • path - the original manual page and section specified (man(1))

This also supports manpages specified as man.1.

注釈

This currently affects only HTML writers but could be expanded in the future.

バージョン 1.7 で追加.

nitpicky

もしもTrueが設定されると、 すべての 参照に対して、参照先が見つからないと警告を出します。デフォルトは False です。コマンドラインスイッチの -n を使用すると、一時的にこの機能を有効にすることもできます。

バージョン 1.0 で追加.

nitpick_ignore

(タイプ, ターゲット) というタプルのリスト(デフォルトは空配列)です。nitpickyモードで生成される警告を無視します。 タイプ にはドメイン名入りのものを設定します。 ('py:func', 'int') あるいは ('envvar', 'LD_LIBRARY_PATH') といった形式になります。

バージョン 1.1 で追加.

nitpick_ignore_regex

An extended version of nitpick_ignore, which instead interprets the type and target strings as regular expressions. Note, that the regular expression must match the whole string (as if the ^ and $ markers were inserted).

For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky warnings for all python entities that start with 'foo' and have 'bar.B' in them, such as ('py:const', 'foo_package.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').

バージョン 4.1 で追加.

numfig

If true, figures, tables and code-blocks are automatically numbered if they have a caption. The numref role is enabled. Obeyed so far only by HTML and LaTeX builders. Default is False.

注釈

このオプションを有効にしていてもいなくても、LaTeXビルダーは常に番号を振ります。

バージョン 1.3 で追加.

numfig_format

A dictionary mapping 'figure', 'table', 'code-block' and 'section' to strings that are used for format of figure numbers. As a special character, %s will be replaced to figure number.

Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'table', 'Listing %s' for 'code-block' and 'Section' for 'section'.

バージョン 1.3 で追加.

numfig_secnum_depth

  • if set to 0, figures, tables and code-blocks are continuously numbered starting at 1.

  • if 1 (default) numbers will be x.1, x.2, ... with x the section number (top level sectioning; no x. if no section). This naturally applies only if section numbering has been activated via the :numbered: option of the toctree directive.

  • 2 means that numbers will be x.y.1, x.y.2, ... if located in a sub-section (but still x.1, x.2, ... if located directly under a section and 1, 2, ... if not in any top level section.)

  • etc...

バージョン 1.3 で追加.

バージョン 1.7 で変更: The LaTeX builder obeys this setting (if numfig is set to True).

smartquotes

If true, the Docutils Smart Quotes transform, originally based on SmartyPants (limited to English) and currently applying to many languages, will be used to convert quotes and dashes to typographically correct entities. Default: True.

バージョン 1.6.6 で追加: It replaces deprecated html_use_smartypants. It applies by default to all builders except man and text (see smartquotes_excludes.)

A docutils.conf file located in the configuration directory (or a global ~/.docutils file) is obeyed unconditionally if it deactivates smart quotes via the corresponding Docutils option. But if it activates them, then smartquotes does prevail.

smartquotes_action

This string customizes the Smart Quotes transform. See the file smartquotes.py at the Docutils repository for details. The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses ....

バージョン 1.6.6 で追加.

smartquotes_excludes

This is a dict whose default is:

{'languages': ['ja'], 'builders': ['man', 'text']}

Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Accepted keys are as above 'builders' or 'languages'. The values are lists.

注釈

Currently, in case of invocation of make with multiple targets, the first target name is the only one which is tested against the 'builders' entry and it decides for all. Also, a make text following make html needs to be issued in the form make text O="-E" to force re-parsing of source files, as the cached ones are already transformed. On the other hand the issue does not arise with direct usage of sphinx-build as it caches (in its default usage) the parsed source files in per builder locations.

ヒント

An alternative way to effectively deactivate (or customize) the smart quotes for a given builder, for example latex, is to use make this way:

make latex O="-D smartquotes_action="

This can follow some make html with no problem, in contrast to the situation from the prior note. It requires Docutils 0.14 or later.

バージョン 1.6.6 で追加.

user_agent

A User-Agent of Sphinx. It is used for a header on HTTP access (ex. linkcheck, intersphinx and so on). Default is "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".

バージョン 2.3 で追加.

tls_verify

If true, Sphinx verifies server certifications. Default is True.

バージョン 1.5 で追加.

tls_cacerts

A path to a certification file of CA or a path to directory which contains the certificates. This also allows a dictionary mapping hostname to the path to certificate file. The certificates are used to verify server certifications.

バージョン 1.5 で追加.

ちなみに

Sphinx uses requests as a HTTP library internally. Therefore, Sphinx refers a certification file on the directory pointed REQUESTS_CA_BUNDLE environment variable if tls_cacerts not set.

today
today_fmt

これらの値は現在の日付をどのようにフォーマットするのか、というものを決めます。これは |today| を置き換える時に使用されます。

  • もし today に空ではない値が設定されたらそれが使用されます。

  • そうでない場合には、 today_fmt で与えられたフォーマットを使い、 time.strftime() で生成された値が使用されます。

The default is now today and a today_fmt of '%b %d, %Y' (or, if translation is enabled with language, an equivalent format for the selected locale).

highlight_language

The default language to highlight source code in. The default is 'default'. It is similar to 'python3'; it is mostly a superset of 'python' but it fallbacks to 'none' without warning if failed. 'python3' and other languages will emit warning if failed.

The value should be a valid Pygments lexer name, see コードサンプルの表示 for more details.

バージョン 0.5 で追加.

バージョン 1.4 で変更: The default is now 'default'. If you prefer Python 2 only highlighting, you can set it back to 'python'.

highlight_options

A dictionary that maps language names to options for the lexer modules of Pygments. These are lexer-specific; for the options understood by each, see the Pygments documentation.

サンプル:

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

A single dictionary of options are also allowed. Then it is recognized as options to the lexer specified by highlight_language:

# configuration for the ``highlight_language``
highlight_options = {'stripall': True}

バージョン 1.3 で追加.

バージョン 3.5 で変更: Allow to configure highlight options for multiple languages

pygments_style

Pygmentsがソースコードをハイライトする際に使用するスタイルの名前を設定します。設定しなければ、HTML出力にはテーマのデフォルトスタイルか、 'sphinx' が選択されます。

バージョン 0.3 で変更: 値に独自のPygmentsスタイルクラスの完全修飾名を指定した場合、カスタムスタイルとして使用されます。

add_function_parentheses

関数とメソッドのロールテキストにカッコを付加するかどうかを決めるブール値です。ロールテキストというのは :func:`input` の input の箇所で、これをTrueにすると、その名前が呼び出し可能オブジェクトであるということが分かるようになります。デフォルトは True です。

add_module_names

モジュール定義がされている場所にある、 py:function などの オブジェクト 名のタイトルのすべてに、モジュール名を付けるかどうかを決めるブール値です。デフォルトは True です。

show_authors

codeauthor と sectionauthor ディレクティブの出力を、ビルドしたファイルに含めるかどうかのブール値です。

modindex_common_prefix

モジュールのインデックスをソートする際に、無視するプリフィックスのリストです。例えば、 ['foo.'] が設定されると、 foo.bar に関しては foo. が削除されて bar になるため、 F ではなく、 B の項目として表示されます。プロジェクトの中のひとつのパッケージについてドキュメントを書く際にこの機能は便利に使えるでしょう。現在はHTMLビルダーについて使用されています。デフォルトは [] です。

バージョン 0.6 で追加.

trim_footnote_reference_space

脚注参照の前のスペースをトリムします。スペースはreSTパーサーが脚注を見分けるためには必要ですが、出力されると見た目があまり良くありません。

バージョン 0.6 で追加.

trim_doctest_flags

Trueの場合、行末のdoctestフラグ ( # doctest: FLAG, ... のようなコメント) もしくは <BLANKLINE> マーカーがPythonのインタラクティブセッション形式のコードブロック(例えば doctests など) で削除されます。デフォルトは True です。doctestに関連して可能なことはまだ多くありますので、詳しくはSphinx拡張モジュールの doctest をご覧ください。

バージョン 1.0 で追加.

バージョン 1.1 で変更: <BLANKLINE> も削除対象にしました。

strip_signature_backslash

Default is False. When backslash stripping is enabled then every occurrence of \\ in a domain directive will be changed to \, even within string literals. This was the behaviour before version 3.0, and setting this variable to True will reinstate that behaviour.

バージョン 3.0 で追加.

国際化のオプション

これらのオプションは、Sphinxの 自然言語サポート に影響します。詳しくは、 国際化 のドキュメントを参照してください。

language

The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, Sphinx will try to substitute individual paragraphs from your documents with the translation sets obtained from locale_dirs. Sphinx will search language-specific figures named by figure_language_filename (e.g. the German version of myfigure.png will be myfigure.de.png by default setting) and substitute them for original figures. In the LaTeX builder, a suitable language will be selected as an option for the Babel package. Default is None, which means that no translation will be done.

バージョン 0.5 で追加.

バージョン 1.4 で変更: 画像の置き換えをサポートするようになりました。

現在は以下の言語をサポートしています:

  • ar -- Arabic

  • bg -- Bulgarian

  • bn -- ベンガル語

  • ca -- カタルーニャ語

  • cak -- Kaqchikel

  • cs -- チェコ語

  • cy -- Welsh

  • da -- デンマーク語

  • de -- ドイツ語

  • el -- Greek

  • en -- 英語

  • eo -- Esperanto

  • es -- スペイン語

  • et -- エストニア語

  • eu -- バスク語

  • fa -- イラン語

  • fi -- フィンランド語

  • fr -- フランス語

  • he -- ヘブライ語

  • hi -- Hindi

  • hi_IN -- Hindi (India)

  • hr -- クロアチア語

  • hu -- ハンガリー語

  • id -- インドネシア

  • it -- イタリア語

  • ja -- 日本語

  • ko -- 韓国語

  • lt -- リトアニア語

  • lv -- ラトビア語

  • mk -- マケドニア語

  • nb_NO -- ノルウェー語ブークモール

  • ne -- ネパール語

  • nl -- オランダ語

  • pl -- ポーランド語

  • pt -- ポルトガル語

  • pt_BR -- ブラジルのポーランド語

  • pt_PT -- ヨーロッパのポルトガル語

  • ro -- ローマ語

  • ru -- ロシア語

  • si -- シンハラ語

  • sk -- スロバキア語

  • sl -- スロベニア語

  • sq -- Albanian

  • sr -- Serbian

  • sr@latin -- Serbian (Latin)

  • sr_RS -- Serbian (Cyrillic)

  • sv -- スウェーデン語

  • ta -- Tamil

  • te -- Telugu

  • tr -- トルコ語

  • uk_UA -- ウクライナ語

  • ur -- Urdu

  • vi -- ベトナム語

  • zh_CN -- 簡体字中国語

  • zh_TW -- 繁体字中国語

locale_dirs

バージョン 0.5 で追加.

追加のSphinxメッセージカタログ( language 参照)を探索するディレクトリを指定します。ここで指定されたパスが、標準の gettext モジュールによって検索されます。

内部メッセージは sphinx ドメインから検索されます; ./locale を設定ファイルに指定した場合には、 ./locale/language/LC_MESSAGES/sphinx.mo という場所に(msgfmt を使って .po にコンパイルされた)メッセージカタログを置かなければなりません。個々のドキュメントのテキストドメインは、 gettext_compact によって決まります。

デフォルトは ['locales'] です。

注釈

The -v option for sphinx-build command is useful to check the locale_dirs config works as expected. It emits debug messages if message catalog directory not found.

バージョン 1.5 で変更: locales ディレクトリをデフォルト値として使うようになりました。

gettext_compact

バージョン 1.1 で追加.

True なら、ドキュメントがトップレベルのプロジェクトファイルだった場合はドキュメントのテキストドメインはそのドキュメント名が使われ、サブディレクトリ以下の場合はサブディレクトリ名が使われます。

If set to string, all document's text domain is this string, making all documents use single text domain.

デフォルトでは markup/code.rst というドキュメントは markup テキストドメインとなります。この設定が False の場合、 markup/code となります。

バージョン 3.3 で変更: The string value is now accepted.

gettext_uuid

もしtrueであれば、SphinxはUUID情報をメッセージカタログの中にバージョントラッキングのために生成します。以下の場合に利用します:

  • uid行を.potファイルの中の各msgidに追加します。

  • 新しいmsgidと前に保存されたmsgidの類似性を比較計算します。この計算には時間がかかります。

もし計算を速くしたいのであれば、C実装のサードパーティパッケージ python-levenshtein を pip install python-levenshtein を使ってインストールしてください。

デフォルト値は False です。

バージョン 1.3 で追加.

gettext_location

もしtrueなら、Sphinxはメッセージカタログ内に位置情報を生成します。

デフォルト値は True です。

バージョン 1.3 で追加.

gettext_auto_build

もしtrueであれば、Sphinxは各翻訳カタログファイルについてmoファイルをビルドします。

デフォルト値は True です。

バージョン 1.3 で追加.

gettext_additional_targets

gettextによる抽出を有効化するためにnameを明示し、i18nへ翻訳を適用します。以下のnameが利用できます:

索引

インデックスの文字列

Literal-block

literal blocks (:: annotation and code-block directive)

Doctest-block

doctestブロック

Raw

rawディレクティブのコンテンツ

Image

image/figure uri

例: gettext_additional_targets = ['literal-block', 'image'] 。

デフォルトは [] です。

バージョン 1.3 で追加.

バージョン 4.0 で変更: The alt text for image is translated by default.

figure_language_filename

The filename format for language-specific figures. The default value is {root}.{language}{ext}. It will be expanded to dirname/filename.en.png from .. image:: dirname/filename.png. The available format tokens are:

  • {root} - the filename, including any path component, without the file extension, e.g. dirname/filename

  • {path} - the directory path component of the filename, with a trailing slash if non-empty, e.g. dirname/

  • {docpath} - the directory path component for the current document, with a trailing slash if non-empty.

  • {basename} - the filename without the directory path or file extension components, e.g. filename

  • {ext} - the file extension, e.g. .png

  • {language} - the translation language, e.g. en

For example, setting this to {path}{language}/{basename}{ext} will expand to dirname/en/filename.png instead.

バージョン 1.4 で追加.

バージョン 1.5 で変更: Added {path} and {basename} tokens.

バージョン 3.2 で変更: Added {docpath} token.

Options for Math

These options influence Math notations.

math_number_all

もし表示されるすべての数式に番号を振りたい場合、このオプションを True にします。デフォルトでは False です。

math_eqref_format

A string used for formatting the labels of references to equations. The {number} place-holder stands for the equation number.

Example: 'Eq.{number}' gets rendered as, for example, Eq.10.

math_numfig

``True``にすると、numfig が有効になっているとき、表示される数式がページをまたいで番号が振られます。:confval:`numfig_secnum_depth`設定は尊重されます。数式の参照には、:rst:role:`numref`ではなく、:rst:role:`eq`ロールを使わなければなりません。デフォルトは ``True``です。

バージョン 1.7 で追加.

HTML出力のオプション

これらのオプションはHTMLとHTMLヘルプ出力、他にもSphinxのHTMLWriterクラスを用いている他のビルダーへ影響します。

html_theme

The "theme" that the HTML output should use. See the section about theming. The default is 'alabaster'.

バージョン 0.6 で追加.

html_theme_options

選択したテーマのルックアンドフィールの設定を行うためのオプションのための辞書です。どのようなオプションがあるかは、テーマごとに異なります。組み込みのテーマで提供されるオプションに関しては、 こちらのセクション を参照してください。

バージョン 0.6 で追加.

html_theme_path

カスタムテーマを含むパスへのリストです。パスはテーマを含むサブディレクトリか、もしくはzipファイルを指定できます。相対パスを設定すると、コンフィグレーションディレクトリからの相対パスになります。

バージョン 0.6 で追加.

html_style

HTMLページに利用するスタイルシートです。ここで指定するファイルは Sphinxの static/ か、カスタムパスの1つである html_static_path に置いてください。デフォルトはテーマで与えられたスタイルシートが利用されます。もしテーマのスタイルシートへいくつかの上書きもしくは追加をしたい場合には、 CSS @import をテーマのスタイルシートをインポートするのに使って下さい。

html_title

Sphinx自身のテンプレートで生成されるHTMLドキュメントの"タイトル"を指定します。ここで設定された値は、それぞれのページ内の <title> タグに対して追加され、ナビゲーションバーの一番トップの要素として使用されます。デフォルト値は '{<project>} v{<revision>} document' となっています。

html_short_title

A shorter "title" for the HTML docs. This is used for links in the header and in the HTML Help docs. If not given, it defaults to the value of html_title.

バージョン 0.4 で追加.

html_baseurl

The base URL which points to the root of the HTML documentation. It is used to indicate the location of document using The Canonical Link Relation. Default: ''.

バージョン 1.8 で追加.

html_codeblock_linenos_style

The style of line numbers for code-blocks.

  • 'table' -- display line numbers using <table> tag

  • 'inline' -- display line numbers using <span> tag (default)

バージョン 3.2 で追加.

バージョン 4.0 で変更: It defaults to 'inline'.

バージョン 4.0 で非推奨.

html_context

テンプレートエンジンのコンテキストとしてわたされる辞書です。これは、 sphinx-build の -A コマンドラインオプションを使って渡すこともできます。

バージョン 0.5 で追加.

If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the docs, or URL that points an image file for the logo. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: None.

バージョン 0.4.1 で追加: 画像ファイルはHTML出力時に _static ディレクトリにコピーされます。もし同名のファイルが存在する場合にはコピーされません。

バージョン 4.0 で変更: Also accepts the URL for the logo file.

html_favicon

If given, this must be the name of an image file (path relative to the configuration directory) that is the favicon of the docs, or URL that points an image file for the favicon. Modern browsers use this as the icon for tabs, windows and bookmarks. It should be a Windows-style icon file (.ico), which is 16x16 or 32x32 pixels large. Default: None.

バージョン 0.4 で追加: 画像ファイルはHTML出力時に _static ディレクトリにコピーされます。もし同名のファイルが存在する場合にはコピーされません。

バージョン 4.0 で変更: Also accepts the URL for the favicon.

html_css_files

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/style.css. The attributes is used for attributes of <link> tag. It defaults to an empty list.

サンプル:

html_css_files = ['custom.css',
                  'https://example.com/css/custom.css',
                  ('print.css', {'media': 'print'})]

As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer Sphinx.add_css_files().

バージョン 1.8 で追加.

バージョン 3.5 で変更: Support priority attribute

html_js_files

A list of JavaScript filename. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/script.js. The attributes is used for attributes of <script> tag. It defaults to an empty list.

サンプル:

html_js_files = ['script.js',
                 'https://example.com/scripts/custom.js',
                 ('custom.js', {'async': 'async'})]

As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer Sphinx.add_css_files().

バージョン 1.8 で追加.

バージョン 3.5 で変更: Support priority attribute

html_static_path

スタイルシートやスクリプトファイルといった、カスタムの静的ファイル類が含まれるパスのリストです。相対パスが設定されると、conf.pyのあるディレクトリからの相対パスとして処理されます。これらのファイルは、テーマが提供する静的ファイルを _static ディレクトリにコピーした後にコピーされるため、 default.css という名前のファイルがあると、テーマで使用する default.css を上書きしてしまうので注意してください。

As these files are not meant to be built, they are automatically excluded from source files.

注釈

For security reasons, dotfiles under html_static_path will not be copied. If you would like to copy them intentionally, please add each filepath to this setting:

html_static_path = ['_static', '_static/.htaccess']

Another way to do that, you can also use html_extra_path. It allows to copy dotfiles under the directories.

バージョン 0.4 で変更: html_static_path で指定されるパスにはサブディレクトリも含めることができます。

バージョン 1.0 で変更: html_static_path 内のエントリーに、単独のファイルを入れることができます。

バージョン 1.8 で変更: The files under html_static_path are excluded from source files.

html_extra_path

robots.txt や .htaccess といった、ドキュメントに直接関連しない追加のファイルが含まれるパスのリストです。相対パスが設定されると、conf.pyのあるディレクトリからの相対パスとして処理されます。これらのファイルは出力先ディレクトリにコピーされます。これによって、同名のファイルが既にある場合は上書きされます。

As these files are not meant to be built, they are automatically excluded from source files.

バージョン 1.2 で追加.

バージョン 1.4 で変更: The dotfiles in the extra directory will be copied to the output directory. And it refers exclude_patterns on copying extra files and directories, and ignores if path matches to patterns.

html_last_updated_fmt

If this is not None, a 'Last updated on:' timestamp is inserted at every page bottom, using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

html_use_smartypants

If true, quotes and dashes are converted to typographically correct entities. Default: True.

バージョン 1.6 で非推奨: To disable smart quotes, use rather smartquotes.

Sphinxはそれぞれの見出しに "パーマリンク" を追加します。マウスをそれぞれのリンクの上に持って行くと、パラグラフサインが表示されます。

この値は、パーマリンクのテキストとして使用されます。デフォルトは "¶" です。 None を指定すると、パーマリンクは表示されなくなります。

バージョン 0.6 で追加: 以前は常に有効になってました。

バージョン 1.1 で変更: 現在では実際に表示されるテキストを文字列で指定します。以前では、ブール型を指定していました。

バージョン 3.5 で非推奨: This has been replaced by html_permalinks

If true, Sphinx will add "permalinks" for each heading and description environment. Default: True.

バージョン 3.5 で追加.

A text for permalinks for each heading and description environment. HTML tags are allowed. Default: a paragraph sign;

バージョン 3.5 で追加.

html_sidebars

カスタムのサイドバーのテンプレートです。設定値は、ドキュメント名をキーに、テンプレート名を値に持つ辞書として設定します。

キーには、globスタイルパターンを含めることができます 1 。この場合、マッチしたすべてのドキュメントには、指定されたサイドバーが設定されます。1つ以上のglobスタイルのパターンがマッチすると、警告が出されます。

辞書の値には、リストか、文字列を設定できます。

  • もしも値がリストの場合には、含めるべきサイドバーテンプレートの完全なリストとして使用されます。もしもデフォルトサイドバーのすべて、もしくはいくつかが含まれていたら、それらはこのリストに含められます。

    The default sidebars (for documents that don't match any pattern) are defined by theme itself. Builtin themes are using these templates by default: ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'].

  • もしも値が文字列だった場合には、指定されたカスタムサイドバーが、 'sourcelink.html' と 'searchbox.html' の間に追加されます。これは、Sphinxの1.0よりも前のバージョンと互換性があります。

バージョン 1.7 で非推奨: a single string value for html_sidebars will be removed in 2.0

組み込みのサイドバーテンプレートは以下のようにビルドされます:

  • localtoc.html -- 現在のドキュメントの、詳細な目次

  • globaltoc.html -- ドキュメントセット全体に関する、荒い粒度の折りたたまれた目次

  • relations.html -- 前のドキュメントと、次のドキュメントへの２つのリンク

  • sourcelink.html -- もし html_show_sourcelink が有効にされている場合に、現在のドキュメントのソースへのリンク

  • searchbox.html -- "クイック検索"ボックス

サンプル:

html_sidebars = {
   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
   'using/windows': ['windowssidebar.html', 'searchbox.html'],
}

これは windowssidebar.html カスタムテンプレートと、クイック検索ボックスをレンダリングし、指定されたドキュメントのサイドバーに組み込みます。その他のドキュメントに関しては、デフォルトサイドバーをビルドします。ただし、ローカルの目次はグローバルな目次に置き換えられます。

バージョン 1.0 で追加: globスタイルのキーが利用できるようになり、複数のサイドバーが設定できるようになりました。

これらの値は、組み込みの scrolls と haiku テーマのように、設定したテーマによっては効果がありません。

html_additional_pages

HTMLページにレンダリングする、追加のHTMLテンプレートを指定します。設定値はドキュメント名をキーに、テンプレート名を値に持つ辞書として設定します。

サンプル:

html_additional_pages = {
    'download': 'customdownload.html',
}

この設定では、 customdownload.html というテンプレートが download.html というページにレンダリングされます。

html_domain_indices

Trueが設定されると、ドメインに特化した索引が、全体の索引に追加されます。Pythonのドメインの場合には、グローバルなモジュールの索引が該当します。デフォルトは True です。

この設定値にはブール型か、生成すべき索引名のリストを設定できます。特定の索引名をしていると、HTMLのファイル名を探しに行きます。例えば、Pythonのモジュール索引は 'py-modindex' という名前を持ちます。

バージョン 1.0 で追加.

html_use_index

Trueが設定されると、HTMLドキュメントに索引を追加します。デフォルトは True です。

バージョン 0.4 で追加.

html_split_index

もしTrueが設定されると、索引が２回作成されます。一つ目は全てのエントリーを含む索引です。2つめは最初の文字ごとにページ分割された索引になります。デフォルトは False です。

バージョン 0.4 で追加.

html_copy_source

Trueに設定されると、 HTMLのビルド時に _sources/name としてreSTのソースファイルが含まれるようになります。デフォルトは True です。

html_copy_source がTrueに設定されていて、かつ、この設定値もTrueに設定された場合に、サイドバーにreSTのソースファイルへのリンクを表示します。デフォルト値は True です。

バージョン 0.6 で追加.

Suffix to be appended to source links (see html_show_sourcelink), unless they have this suffix already. Default is '.txt'.

バージョン 1.5 で追加.

html_use_opensearch

If nonempty, an OpenSearch description file will be output, and all pages will contain a <link> tag referring to it. Since OpenSearch doesn't support relative URLs for its search page location, the value of this option must be the base URL from which these documents are served (without trailing slash), e.g. "https://docs.python.org". The default is ''.

html_file_suffix

HTMLファイルを生成するときに、ファイル名の末尾に追加される文字列として使用されます。デフォルトでは ".html" となります。

バージョン 0.4 で追加.

HTMLファイルに対して生成されるリンクの末尾に付けられる文字列です。デフォルト値としては html_file_suffix の値が設定されます。他のウェブサーバのセットアップをサポートする場合などに、別の値を設定できます。

バージョン 0.6 で追加.

もしTrueに設定されると、 "(C) Copyright ..." という文字列をHTMLのフッターに出力します。デフォルトは True です。

バージョン 1.0 で追加.

html_show_sphinx

もしTrueが設定されると、 "このドキュメントは Sphinx で生成しました。" という説明がHTMLのフッターに追加されます。デフォルトは True です。

バージョン 0.4 で追加.

html_output_encoding

HTML出力ファイルのエンコーディングを指定します。デフォルトは 'utf-8' です。このエンコーディング名Pythonのエンコーディング指定と、HTMLの charset の両方で使用できる名前でなければなりません。

バージョン 1.0 で追加.

html_compact_lists

If true, a list all whose items consist of a single paragraph and/or a sub-list all whose items etc... (recursive definition) will not use the <p> element for any of its items. This is standard docutils behavior. Default: True.

バージョン 1.0 で追加.

html_secnumber_suffix

セクション番号のサフィックスです。デフォルトは ". " です。 " " を指定すると、セクション番号の末尾のピリオドが表示されなくなります。

バージョン 1.0 で追加.

html_search_language

HTMLの全文検索インデックスの生成に使用する言語を設定します。デフォルトは language で選択された言語が使用されます。もし、該当する言語のサポートがない場合には、 "en" が選択され、英語処理のアルゴリズムが使用されます。

現在では次の言語をサポートしています:

  • da -- デンマーク語

  • nl -- オランダ語

  • en -- 英語

  • fi -- フィンランド語

  • fr -- フランス語

  • de -- ドイツ語

  • hu -- ハンガリー語

  • it -- イタリア語

  • ja -- 日本語

  • no -- ノルウェー語

  • pt -- ポルトガル語

  • ro -- ローマ語

  • ru -- ロシア語

  • es -- スペイン語

  • sv -- スウェーデン語

  • tr -- トルコ語

  • zh -- 中国語

ビルドスピードの向上

各言語 (日本語を除く) はそれぞれ独自のステミングアルゴリズムを提供します。SphinxはデフォルトではPythonの実装を用います。インデックスファイルのビルドを速くするために、C言語での実装を使用できます。

バージョン 1.1 で追加: 英語および日本語のサポート

バージョン 1.3 で変更: さらに複数言語を追加

html_search_options

検索言語のオプションとして使用される、設定値の辞書です。デフォルトでは空辞書になります。意味は選択された言語によって変わります。

英語ではオプションはありません。

日本語では次のオプションをサポートします。

のデータ型

type is dotted module path string to specify Splitter implementation which should be derived from sphinx.search.ja.BaseSplitter. If not specified or None is specified, 'sphinx.search.ja.DefaultSplitter' will be used.

以下のモジュールから選択できます:

'sphinx.search.ja.DefaultSplitter'

TinySegmenterアルゴリズム。これがデフォルトの分かち書きアルゴリズムです。

'sphinx.search.ja.MecabSplitter'

MeCab バインディング。この分かち書きアルゴリズムを使うには、 'mecab' のpython バインディングかダイナミックリンクライブラリ(Linuxでは 'libmecab.so' 、Windowsでは 'libmecab.dll' )が必要です。

'sphinx.search.ja.JanomeSplitter'

Janome binding. To use this splitter, Janome is required.

バージョン 1.6 で非推奨: 'mecab', 'janome' and 'default' is deprecated. To keep compatibility, 'mecab', 'janome' and 'default' are also acceptable.

他のオプションは選択した分かち書きアルゴリズムによって異なります。

'mecab' のオプション:
dic_enc

dic_enc option では MeCabアルゴリズムのエンコーディングを指定します。

dict

dict option では MeCabアルゴリズムで使用する辞書を指定します。

lib

lib option ではPythonバインディングがインストールされていない場合に、MeCabライブラリをctypesから探すためのライブラリ名を指定します。

例えば:

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab.dic',
    'lib': '/path/to/libmecab.so',
}
'janome' のオプション:
user_dic

user_dic option はJanomeのユーザー辞書ファイルへのパスです。

user_dic_enc

user_dic_enc option は user_dic オプションで設定されたユーザー辞書ファイルのエンコーディングです。デフォルト値は 'utf8' です。

バージョン 1.1 で追加.

バージョン 1.4 で変更: 日本語での html_search_options は再構成され、 type 設定で分かち書きアルゴリズムを自由に設定できるようになりました。

中国語では次のオプションをサポートします。

  • dict -- カスタム辞書を使用したい場合、 jieba 辞書のパスを指定します。

html_search_scorer

検索結果のスコア計算を実装したjavascriptのファイル名(設定ディレクトリからの相対パス)を設定します。もし空の場合、デフォルトのファイルが使用されます。

バージョン 1.2 で追加.

真を指定した場合で、'target'オプションか'scale', ’width', 'height' といった拡大縮小オプションが指定されていない場合、画像からオリジナル画像へのリンクが設定されます。デフォルトは True です。

Document authors can this feature manually with giving no-scaled-link class to the image:

.. image:: sphinx.png
   :scale: 50%
   :class: no-scaled-link

バージョン 1.3 で追加.

バージョン 3.0 で変更: It is disabled for images having no-scaled-link class

html_math_renderer

The name of math_renderer extension for HTML output. The default is 'mathjax'.

バージョン 1.8 で追加.

html_experimental_html5_writer

Output is processed with HTML5 writer. Default is False.

バージョン 1.6 で追加.

バージョン 2.0 で非推奨.

html4_writer

Output is processed with HTML4 writer. Default is False.

Options for Single HTML output

singlehtml_sidebars

Custom sidebar templates, must be a dictionary that maps document names to template names. And it only allows a key named 'index'. All other keys are ignored. For more information, refer to html_sidebars. By default, it is same as html_sidebars.

Options for HTML help output

htmlhelp_basename

HTMLヘルプビルダーについて、出力ファイルのベース名を設定します。デフォルト値は 'pydoc' です。

htmlhelp_file_suffix

This is the file name suffix for generated HTML help files. The default is ".html".

バージョン 2.0 で追加.

Suffix for generated links to HTML files. The default is ".html".

バージョン 2.0 で追加.

AppleHelp出力のオプション

バージョン 1.3 で追加.

These options influence the Apple Help output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

注釈

Apple Help output will only work on Mac OS X 10.6 and higher, as it requires the hiutil and codesign command line tools, neither of which are Open Source.

You can disable the use of these tools using applehelp_disable_external_tools, but the result will not be a valid help book until the indexer is run over the .lproj folders within the bundle.

applehelp_bundle_name

Apple Help Bookのベース名です。デフォルトでは project 名が使用されます。

applehelp_bundle_id

ヘルプブックバンドルのバンドルID

警告

Appleヘルプの生成を行うためには設定が*必須*です。

applehelp_dev_region

The development region. Defaults to 'en-us', which is Apple’s recommended setting.

applehelp_bundle_version

The bundle version (as a string). Defaults to '1'.

applehelp_icon

The help bundle icon file, or None for no icon. According to Apple's documentation, this should be a 16-by-16 pixel version of the application's icon with a transparent background, saved as a PNG file.

applehelp_kb_product

The product tag for use with applehelp_kb_url. Defaults to '<project>-<release>'.

applehelp_kb_url

The URL for your knowledgebase server, e.g. https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer will replace the values 'product', 'query' and 'lang' at runtime with the contents of applehelp_kb_product, the text entered by the user in the search box and the user's system language respectively.

デフォルトは None でリモート検索を行いません。

applehelp_remote_url

The URL for remote content. You can place a copy of your Help Book's Resources folder at this location and Help Viewer will attempt to use it to fetch updated content.

e.g. if you set it to https://example.com/help/Foo/ and Help Viewer wants a copy of index.html for an English speaking customer, it will look at https://example.com/help/Foo/en.lproj/index.html.

Defaults to None for no remote content.

applehelp_index_anchors

If True, tell the help indexer to index anchors in the generated HTML. This can be useful for jumping to a particular topic using the AHLookupAnchor function or the openHelpAnchor:inBook: method in your code. It also allows you to use help:anchor URLs; see the Apple documentation for more information on this topic.

applehelp_min_term_length

Controls the minimum term length for the help indexer. Defaults to None, which means the default will be used.

applehelp_stopwords

Either a language specification (to use the built-in stopwords), or the path to a stopwords plist, or None if you do not want to use stopwords. The default stopwords plist can be found at /usr/share/hiutil/Stopwords.plist and contains, at time of writing, stopwords for the following languages:

言語

コード

English

en

German

de

Spanish

es

French

fr

Swedish

sv

Hungarian

hu

Italian

it

Defaults to language, or if that is not set, to en.

applehelp_locale

Specifies the locale to generate help for. This is used to determine the name of the .lproj folder inside the Help Book’s Resources, and is passed to the help indexer.

Defaults to language, or if that is not set, to en.

applehelp_title

Specifies the help book title. Defaults to '<project> Help'.

applehelp_codesign_identity

Specifies the identity to use for code signing, or None if code signing is not to be performed.

Defaults to the value of the environment variable CODE_SIGN_IDENTITY, which is set by Xcode for script build phases, or None if that variable is not set.

applehelp_codesign_flags

A list of additional arguments to pass to codesign when signing the help book.

Defaults to a list based on the value of the environment variable OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script build phases, or the empty list if that variable is not set.

applehelp_indexer_path

The path to the hiutil program. Defaults to '/usr/bin/hiutil'.

applehelp_codesign_path

The path to the codesign program. Defaults to '/usr/bin/codesign'.

applehelp_disable_external_tools

If True, the builder will not run the indexer or the code signing tool, no matter what other settings are specified.

This is mainly useful for testing, or where you want to run the Sphinx build on a non-Mac OS X platform and then complete the final steps on OS X for some reason.

デフォルト値は False です。

epub出力のオプション

These options influence the epub output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. The actual values for some of the options is not really important, they just have to be entered into the Dublin Core metadata.

epub_basename

epubファイルのベース名です。デフォルトでは project 名が使用されます。

epub_theme

epub出力時のHTMLテーマです。デフォルトのテーマは小さい画面サイズで見るような調整がされおらず、HTMLのテーマと同じになっていて、epub出力は賢くありません。デフォルトは 'epub' で、このテーマはビジュアルなための空間を減らすようにデザインされています。

epub_theme_options

選択したテーマのルックアンドフィールの設定を行うためのオプションのための辞書です。どのようなオプションがあるかは、テーマごとに異なります。組み込みのテーマで提供されるオプションに関しては、 こちらのセクション を参照してください。

バージョン 1.2 で追加.

epub_title

The title of the document. It defaults to the html_title option but can be set independently for epub creation. It defaults to the project option.

バージョン 2.0 で変更: It defaults to the project option.

epub_description

The description of the document. The default value is 'unknown'.

バージョン 1.4 で追加.

バージョン 1.5 で変更: Renamed from epub3_description

epub_author

The author of the document. This is put in the Dublin Core metadata. It defaults to the author option.

epub_contributor

EPUB 出版物の内容の作成に二次的な役割を果たした人物、組織などの名前。デフォルトは 'unknown' です。

バージョン 1.4 で追加.

バージョン 1.5 で変更: Renamed from epub3_contributor

epub_language

ドキュメントの言語設定です。この設定値はダブリン・コア・メタデータの中に出力されます。デフォルトでは、 language オプションが設定されるか、もしそれも設定されていなければ 'en' になります。

epub_publisher

The publisher of the document. This is put in the Dublin Core metadata. You may use any sensible string, e.g. the project homepage. The defaults to the author option.

ドキュメントの著作権表示です。デフォルトでは copyright オプションと同じですが、epub作成時のみの名前が設定できるようになります。

epub_identifier

ドキュメントの識別子です。この設定値はダブリン・コア・メタデータの中に出力されます。出版物であれば、ISBNコードを入れることになりますが、そうでない場合にはプロジェクトのウェブサイトなどの別のスキーマを使うこともできます。デフォルト値は 'unknown' です。

epub_scheme

epub_identifier に使用する、出版物のスキーマです。この設定値はダブリン・コア・メタデータの中に出力されます。出版物であれば、 'ISBN' になります。プロジェクトのウェブサイトのURLを指定するのであれば、 'URL' を使うのが良いでしょう。デフォルト値は 'unknown' です。

epub_uid

A unique identifier for the document. This is put in the Dublin Core metadata. You may use a XML's Name format string. You can't use hyphen, period, numbers as a first character. The default value is 'unknown'.

epub_cover

表紙ページの情報を設定します。表紙画像のファイル名と、HTMLテンプレートを含むタプルを設定します。レンダリングされたHTMLの表紙ページは、 content.opf の最初の項目として指定されます。もしテンプレートのファイル名が空の場合は、HTMLの表紙ページは作られません。また、空のタプルが設定されると、一切表紙は作られません。

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()

デフォルト値は () です。

バージョン 1.1 で追加.

epub_css_files

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. For more information, see html_css_files.

バージョン 1.8 で追加.

epub_guide

content.opf のガイド要素用メタデータ。これは、オプションのガイド情報の type, uri, title を含むタプルのシーケンスです。詳細については http://idpf.org/epub で OPF のドキュメントを参照してください。可能なら cover と toc タイプに対するデフォルトエントリが自動的に挿入されます。しかし、デフォルトエントリが適切でない場合、タイプは明示的に上書きできます。例:

epub_guide = (('cover', 'cover.html', u'Cover Page'),)

デフォルト値は () です。

epub_pre_files

Sphinxによって生成されたテキストの前に追加されるファイル群を指定します。ファイル名とタイトルが組になったタプルを含む配列となります。もしタイトルが空の場合には、 toc.ncx には追加されません。 サンプル:

epub_pre_files = [
    ('index.html', 'Welcome'),
]

デフォルト値は [] です。

epub_post_files

Sphinxによって生成されたテキストの後ろに追加されるファイル群を指定します。ファイル名とタイトルが組になったタプルを含む配列となります。このオプションは、追加のAppendixとして使用されます。もしタイトルが空の場合には、 toc.ncx には追加されません。デフォルト値は [] です。

epub_exclude_files

buildディレクトリには生成されたりコピーされるが、epubファイルの中には含めないファイルのリストを指定します。デフォルト値は [] です。

epub_tocdepth

toc.ncx という目次ファイルに含める、セクションタイトルの階層数を指定します。1以上の数値でなければなりません。デフォルト値は 3 です。あまり深いと、ユーザが見て辿るのが難しくなることに注意しましょう。

epub_tocdup

このフラグはネストしたtocリストの最初に再びtocエントリーが挿入されたかを確認します。これは章の最初への誘導を簡単に出来ますが、１つのリストの異なるエントリーを混同するため混乱する可能性があります。デフォルト値は True です。

epub_tocscope

この設定は epub の目次に含まれる項目の範囲を決定します。設定は以下の値をとることができます:

  • 'default' -- hidden でない全ての項目が目次に含まれるようになります(デフォルト)

  • 'includehidden' -- 全ての項目が目次に含まれるようになります

バージョン 1.2 で追加.

epub_fix_images

This flag determines if sphinx should try to fix image formats that are not supported by some epub readers. At the moment palette images with a small color table are upgraded. You need Pillow, the Python Image Library, installed to use this option. The default value is False because the automatic conversion may lose information.

バージョン 1.2 で追加.

epub_max_image_width

このオプションは、画像の最大幅を指定します。このオプションが 0 より大きな値に設定されている場合、与えられた値より大きな幅を持つ画像は相応に縮小されます。このオプションが 0 の場合、スケーリングは行なわれません。デフォルト値は 0 です。このオプションを使用するためには Python Image Library (PIL) をインストールする必要があります。

バージョン 1.2 で追加.

epub_show_urls

URLアドレスを表示するかどうかを設定します。このオプションは、リンクされたURLを表示する必要がないリーダーで便利です。次の値のどれかを指定します。

  • 'inline' -- カッコで行中にURLを表示します(デフォルト)。

  • 'footnote' -- URLを脚注に表示します。

  • 'no' -- URLを表示しません

行中にURLを表示する場合、 link-target クラスに対するCSSを定義することでカスタマイズできます。

バージョン 1.2 で追加.

epub_use_index

Trueであれば、epubドキュメントにインデックスが追加されます。デフォルトでは html_use_index オプションですが、epub作成ではhtmlの設定とは別に設定出来ます。

バージョン 1.2 で追加.

epub_writing_mode

It specifies writing direction. It can accept 'horizontal' (default) and 'vertical'

epub_writing_mode

'horizontal'

'vertical'

writing-mode 2

horizontal-tb

vertical-rl

page progression

left to right

right to left

iBook's Scroll Theme support

scroll-axis is vertical.

scroll-axis is horizontal.
2

https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode

LaTeX出力のオプション

これらのオプションはLaTeX出力に影響を与えます。

latex_engine

The LaTeX engine to build the docs. The setting can have the following values:

  • 'pdflatex' -- PDFLaTeX (default)

  • 'xelatex' -- XeLaTeX

  • 'lualatex' -- LuaLaTeX

  • 'platex' -- pLaTeX

  • 'uplatex' -- upLaTeX (default if language is 'ja')

'pdflatex''s support for Unicode characters is limited.

注釈

2.0 adds to 'pdflatex' support in Latin language document of occasional Cyrillic or Greek letters or words. This is not automatic, see the discussion of the latex_elements 'fontenc' key.

If your project uses Unicode characters, setting the engine to 'xelatex' or 'lualatex' and making sure to use an OpenType font with wide-enough glyph coverage is often easier than trying to make 'pdflatex' work with the extra Unicode characters. Since Sphinx 2.0 the default is the GNU FreeFont which covers well Latin, Cyrillic and Greek.

バージョン 2.1.0 で変更: Use xelatex (and LaTeX package xeCJK) by default for Chinese documents.

バージョン 2.2.1 で変更: Use xelatex by default for Greek documents.

バージョン 2.3 で変更: Add uplatex support.

バージョン 4.0 で変更: uplatex becomes the default setting of Japanese documents.

Contrarily to MathJaX math rendering in HTML output, LaTeX requires some extra configuration to support Unicode literals in math: the only comprehensive solution (as far as we know) is to use 'xelatex' or 'lualatex' and to add r'\usepackage{unicode-math}' (e.g. via the latex_elements 'preamble' key). You may prefer r'\usepackage[math-style=literal]{unicode-math}' to keep a Unicode literal such as α (U+03B1) for example as is in output, rather than being rendered as \(\alpha\).

latex_documents

This value determines how to group the document tree into LaTeX source files. It must be a list of tuples (startdocname, targetname, title, author, theme, toctree_only), where the items are:

startdocname

String that specifies the document name of the LaTeX file's master document. All documents referenced by the startdoc document in TOC trees will be included in the LaTeX file. (If you want to use the default root document for your LaTeX build, provide your root_doc here.)

targetname

File name of the LaTeX file in the output directory.

title

LaTeX document title. Can be empty to use the title of the startdoc document. This is inserted as LaTeX markup, so special characters like a backslash or ampersand must be represented by the proper LaTeX commands if they are to be inserted literally.

author

Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \\and to separate multiple authors, as in: 'John \\and Sarah' (backslashes must be Python-escaped to reach LaTeX).

theme

LaTeX theme. See latex_theme.

toctree_only

Must be True or False. If true, the startdoc document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output.

バージョン 1.2 で追加: 以前は、あなたのドキュメントクラスを使用するには、ドキュメントクラス名を"sphinx"で始める必要がありました。これはもはや必要ありません。

バージョン 0.3 で追加: 6番目の toctree_only が追加されました。現在でも、5要素のタプルも指定できます。

このオプションが設定されると、ドキュメントのロゴとして使用されます。指定されるのは、設定ディレクトリからの相対パスの、イメージファイル名でなければなりません。タイトルページのトップに表示されます。デフォルトでは None です。

latex_toplevel_sectioning

This value determines the topmost sectioning unit. It should be chosen from 'part', 'chapter' or 'section'. The default is None; the topmost sectioning unit is switched by documentclass: section is used if documentclass will be howto, otherwise chapter will be used.

Note that if LaTeX uses \part command, then the numbering of sectioning units one level deep gets off-sync with HTML numbering, because LaTeX numbers continuously \chapter (or \section for howto.)

バージョン 1.4 で追加.

latex_appendices

すべてのマニュアルのAppendixに追加されるドキュメント名のリストです。

latex_domain_indices

Trueが設定されると、ドメインに特化した索引が、全体の索引に追加されます。Pythonのドメインの場合には、グローバルなモジュールの索引が該当します。デフォルトは True です。

html_domain_indices と同じく、この設定値にはブール型か、生成すべき索引名のリストを設定できます。

バージョン 1.0 で追加.

latex_show_pagerefs

Trueに設定されると内部参照の後ろにページ参照が追加されます。これはマニュアルを紙に印刷して利用する場合に大変便利です。デフォルトは False です。

バージョン 1.0 で追加.

latex_show_urls

URLアドレスを表示するかどうかを設定します。このオプションは、マニュアルを印刷する場合に便利です。次の値のどれかを指定します。

  • 'no' -- URLを表示しません(デフォルト)

  • 'footnote' -- URLを脚注に表示します。

  • 'inline' -- カッコで行中にURLを表示します。

バージョン 1.0 で追加.

バージョン 1.1 で変更: この設定値は文字列を指定するようになりました。以前ではbool値で、Trueの時に 'inline' 表示されていました。後方互換性の維持のために、 True が設定されても動作するようになっています。

latex_use_latex_multicolumn

The default is False: it means that Sphinx's own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, ...) but may have problems if the tabularcolumns directive was used to inject LaTeX mark-up of the type >{..}, <{..}, @{..} as column specification.

Setting to True means to use LaTeX's standard \multicolumn; this is incompatible with literal blocks in the horizontally merged cell, and also with multiple paragraphs in such cell if the table is rendered using tabulary.

バージョン 1.6 で追加.

latex_use_xindy

If True, the PDF build from the LaTeX files created by Sphinx will use xindy (doc) rather than makeindex for preparing the index of general terms (from index usage). This means that words with UTF-8 characters will get ordered correctly for the language.

  • This option is ignored if latex_engine is 'platex' (Japanese documents; mendex replaces makeindex then).

  • The default is True for 'xelatex' or 'lualatex' as makeindex, if any indexed term starts with a non-ascii character, creates .ind files containing invalid bytes for UTF-8 encoding. With 'lualatex' this then breaks the PDF build.

  • The default is False for 'pdflatex' but True is recommended for non-English documents as soon as some indexed terms use non-ascii characters from the language script.

Sphinx adds to xindy base distribution some dedicated support for using 'pdflatex' engine with Cyrillic scripts. And whether with 'pdflatex' or Unicode engines, Cyrillic documents handle correctly the indexing of Latin names, even with diacritics.

バージョン 1.8 で追加.

latex_elements

バージョン 0.5 で追加.

Its documentation has moved to LaTeX のカスタマイズ.

latex_docclass

'howto' と 'manual' から実際にSphinxのクラスとして使われるdocument classへのマッピングをする辞書です。デフォルトでは 'howto' には 'article', 'manual' には 'report' が使われます。

バージョン 1.0 で追加.

バージョン 1.5 で変更: In Japanese docs (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.

latex_additional_files

設定ディレクトリからの相対パスのファイル名のリストです。LaTeX出力のビルドが行われる時にビルドディレクトリに出力されます。 latex_elements などで参照していて、Sphinxが自動ではコピーしないファイルのコピーに使うと便利です。なお、ソースファイルの中で .. image:: を使って参照しているイメージファイルは、自動的にコピーされます。

ファイルの自動コピー時に、ファイル名が衝突しないように設定する必要があります。

バージョン 0.6 で追加.

バージョン 1.2 で変更: This overrides the files which is provided from Sphinx such as sphinx.sty.

latex_theme

The "theme" that the LaTeX output should use. It is a collection of settings for LaTeX output (ex. document class, top level sectioning unit and so on).

As a built-in LaTeX themes, manual and howto are bundled.

manual

A LaTeX theme for writing a manual. It imports the report document class (Japanese documents use jsbook).

howto

A LaTeX theme for writing an article. It imports the article document class (Japanese documents use jreport rather). latex_appendices is available only for this theme.

It defaults to 'manual'.

バージョン 3.0 で追加.

latex_theme_options

A dictionary of options that influence the look and feel of the selected theme.

バージョン 3.1 で追加.

latex_theme_path

A list of paths that contain custom LaTeX themes as subdirectories. Relative paths are taken as relative to the configuration directory.

バージョン 3.0 で追加.

テキスト出力のオプション

これらのオプションは、テキスト出力に影響を与えます。

text_newlines

テキスト出力で、どの改行コードを使用するのかを決定します。

  • 'unix': Unixスタイルの改行コード(\n)

  • 'windows': Widnowsスタイルの改行コード(\r\n)

  • 'native': ビルドされた環境の改行コードに合わせます。

デフォルトは 'unix' です。

バージョン 1.1 で追加.

text_sectionchars

7文字の文字列で、セクションタイトルで指定する記号を設定します。それぞれ、1文字目が最初のヘッダ、2文字目が2段目のヘッダとして使用されます。

デフォルトは '*=-~"+`' です。

バージョン 1.1 で追加.

text_add_secnumbers

A boolean that decides whether section numbers are included in text output. Default is True.

バージョン 1.7 で追加.

text_secnumber_suffix

Suffix for section numbers in text output. Default: ". ". Set to " " to suppress the final dot on section numbers.

バージョン 1.7 で追加.

manページ出力のオプション

これらのオプションは、manページ出力に影響を与えます。

man_pages

この値はドキュメントツリーをどのようにグループ化してmanページに含めるか決定します。これは、 (startdocname, name, description, authors, section) というタプルのリストでなければなりません。それぞれの項目は次のような意味を持ちます。

startdocname

String that specifies the document name of the manual page's master document. All documents referenced by the startdoc document in TOC trees will be included in the manual file. (If you want to use the default root document for your manual pages build, use your root_doc here.)

name

Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).

description

Description of the manual page. This is used in the NAME section.

authors

A list of strings with authors, or a single string. Can be an empty string or list if you do not want to automatically generate an AUTHORS section in the manual page.

section

The manual page section. Used for the output file name as well as in the manual page header.

バージョン 1.0 で追加.

man_show_urls

もし True が設定されると、リンクのあとにURLのアドレスが追加されます。デフォルトは False です。

バージョン 1.1 で追加.

man_make_section_directory

If true, make a section directory on build man page. Default is True.

バージョン 3.3 で追加.

バージョン 4.0 で変更: The default is changed to False from True.

バージョン 4.0.2 で変更: The default is changed to True from False again.

Texinfo出力のオプション

これらのオプションは、Texinfo出力に影響を与えます。

texinfo_documents

この値はドキュメントツリーをどのようにグループ化してTexinfoソースに含めるか決定します。これは、 (startdocname, targetname, title, author, dir_entry, description, category, toctree_only) というタプルのリストでなければなりません。それぞれの項目は次のような意味を持ちます。

startdocname

String that specifies the document name of the the Texinfo file's master document. All documents referenced by the startdoc document in TOC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your root_doc here.)

targetname

File name (no extension) of the Texinfo file in the output directory.

title

Texinfo document title. Can be empty to use the title of the startdoc document. Inserted as Texinfo markup, so special characters like @ and {} will need to be escaped to be inserted literally.

author

Author for the Texinfo document. Inserted as Texinfo markup. Use @* to separate multiple authors, as in: 'John@*Sarah'.

dir_entry

The name that will appear in the top-level DIR menu file.

description

Descriptive text to appear in the top-level DIR menu file.

category

Specifies the section which this entry will appear in the top-level DIR menu file.

toctree_only

Must be True or False. If true, the startdoc document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo output.

バージョン 1.1 で追加.

texinfo_appendices

すべてのマニュアルのAppendixに追加されるドキュメント名のリストです。

バージョン 1.1 で追加.

texinfo_domain_indices

Trueが設定されると、ドメインに特化した索引が、全体の索引に追加されます。Pythonのドメインの場合には、グローバルなモジュールの索引が該当します。デフォルトは True です。

html_domain_indices と同じく、この設定値にはブール型か、生成すべき索引名のリストを設定できます。

バージョン 1.1 で追加.

texinfo_show_urls

URLアドレスを表示するかどうかを設定します。

  • 'footnote' -- URLを脚注に表示します。(デフォルト)

  • 'no' -- URLを表示しません

  • 'inline' -- カッコで行中にURLを表示します。

バージョン 1.1 で追加.

texinfo_no_detailmenu

Trueの場合、ドキュメントの"トップ"ノードのメニューが持つ、個々のサブノードエントリー中にある @detailmenu を生成しません。デフォルトでは False です。

バージョン 1.2 で追加.

texinfo_elements

Texinfoに含められる、スニペットを含む辞書です。Sphinxがデフォルトで .texi ファイルに出力する値をオーバーライドできます。

  • オーバーライドできるキーには、次のようなものがあります:

    'paragraphindent'

    それぞれのパラグラフの最初の行のインデントで使うスペースです。デフォルトは 2 で、 0 ではインデントが行われなくなります。

    'exampleindent'

    サンプルや、リテラルブロックで使うインデント数です。デフォルトは 4 で、 0 が設定されるとインデントが行われなくなります。

    'preamble'

    Texinfoはこのファイルの先頭付近に挿入されます。

    'copying'

    Texinfoマークアップは @copying ブロックの中に挿入され、タイトルの後に表示されます。デフォルトではプロジェクトのシンプルなタイトルページです。

  • 次のようなキーは、他のオプションによって指定されるため、オーバーライドすべきではありません:

    'author' 'body' 'date' 'direntry' 'filename' 'project' 'release' 'title'

バージョン 1.1 で追加.

Options for QtHelp output

These options influence qthelp output. As this builder derives from the HTML builder, the HTML options also apply where appropriate.

qthelp_basename

The basename for the qthelp file. It defaults to the project name.

qthelp_namespace

The namespace for the qthelp file. It defaults to org.sphinx.<project_name>.<project_version>.

qthelp_theme

The HTML theme for the qthelp output. This defaults to 'nonav'.

qthelp_theme_options

選択したテーマのルックアンドフィールの設定を行うためのオプションのための辞書です。どのようなオプションがあるかは、テーマごとに異なります。組み込みのテーマで提供されるオプションに関しては、 こちらのセクション を参照してください。

リンクチェックビルダーのオプション

linkcheck_ignore

linkcheck が行われたときに、無視するURIを決定する、正規表現のリストです。次のように設定します。例:

linkcheck_ignore = [r'http://localhost:\d+/']

バージョン 1.1 で追加.

linkcheck_request_headers

A dictionary that maps baseurls to HTTP request headers.

The key is a URL base string like "https://sphinx-doc.org/". To specify headers for other hosts, "*" can be used. It matches all hosts only when the URL does not match other settings.

The value is a dictionary that maps header name to its value.

例:

linkcheck_request_headers = {
    "https://sphinx-doc.org/": {
        "Accept": "text/html",
        "Accept-Encoding": "utf-8",
    },
    "*": {
        "Accept": "text/html,application/xhtml+xml",
    }
}

バージョン 3.1 で追加.

linkcheck_retries

linkcheckビルダーが個々のURLが無効であると判定するまでの試行回数。デフォルトでは1回。

バージョン 1.4 で追加.

linkcheck_timeout

A timeout value, in seconds, for the linkcheck builder. The default is to use Python's global socket timeout.

バージョン 1.1 で追加.

linkcheck_workers

リンクチェックを行う、ワーカースレッドの数を設定します。デフォルトは5スレッドです。

バージョン 1.1 で追加.

linkcheck_anchors

true または false で、リンク中の #anchor の有効性をチェックするかどうかを表します。これはドキュメント全体をダウンロードする必要があるので、有効にした場合かなり遅くなります。デフォルトは True です。

バージョン 1.2 で追加.

linkcheck_anchors_ignore

A list of regular expressions that match anchors Sphinx should skip when checking the validity of anchors in links. This allows skipping anchors that a website's JavaScript adds to control dynamic pages or when triggering an internal REST request. Default is ["^!"].

注釈

If you want to ignore anchors of a specific page or of pages that match a specific pattern (but still check occurrences of the same page(s) that don't have anchors), use linkcheck_ignore instead, for example as follows:

linkcheck_ignore = [
   'https://www.sphinx-doc.org/en/1.7/intro.html#'
]

バージョン 1.5 で追加.

linkcheck_auth

Pass authentication information when doing a linkcheck build.

A list of (regex_pattern, auth_info) tuples where the items are:

regex_pattern

A regular expression that matches a URI.

auth_info

Authentication information to use for that URI. The value can be anything that is understood by the requests library (see requests Authentication for details).

The linkcheck builder will use the first matching auth_info value it can find in the linkcheck_auth list, so values earlier in the list have higher priority.

サンプル:

linkcheck_auth = [
  ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
  ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
]

バージョン 2.3 で追加.

linkcheck_rate_limit_timeout

The linkcheck builder may issue a large number of requests to the same site over a short period of time. This setting controls the builder behavior when servers indicate that requests are rate-limited.

If a server indicates when to retry (using the Retry-After header), linkcheck always follows the server indication.

Otherwise, linkcheck waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the linkcheck_rate_limit_timeout. By default, the timeout is 5 minutes.

バージョン 3.4 で追加.

XML出力のオプション

xml_pretty

もし True の場合、XMLを整形して表示します。デフォルトは True です。

バージョン 1.2 で追加.

脚注

1(1,2)

"GLOB"文法に関する追加説明: 標準のシェル構文で使用できる *, ?, [...], [!...] が使用できます。これらはスラッシュ(/)にはマッチしません。 ** を使用すると、スラッシュ(/)も 含む すべての文字列に対してマッチします。

Options for the C domain

c_id_attributes

A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been #define d for portability.

バージョン 3.0 で追加.

c_paren_attributes

A list of strings that the parser additionally should accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). This can for example be used when attributes have been #define d for portability.

バージョン 3.0 で追加.

c_allow_pre_v3

A boolean (default False) controlling whether to parse and try to convert pre-v3 style type directives and type roles.

バージョン 3.2 で追加.

バージョン 3.2 で非推奨: Use the directives and roles added in v3.

c_warn_on_allowed_pre_v3

A boolean (default True) controlling whether to warn when a pre-v3 style type directive/role is parsed and converted.

バージョン 3.2 で追加.

バージョン 3.2 で非推奨: Use the directives and roles added in v3.

C++ ドメインのオプション

cpp_index_common_prefix

A list of prefixes that will be ignored when sorting C++ objects in the global index. For example ['awesome_lib::'].

バージョン 1.5 で追加.

cpp_id_attributes

A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been #define d for portability.

バージョン 1.5 で追加.

cpp_paren_attributes

A list of strings that the parser additionally should accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). This can for example be used when attributes have been #define d for portability.

バージョン 1.5 で追加.

Options for the Python domain

python_use_unqualified_type_names

If true, suppress the module name of the python reference if it can be resolved. The default is False.

バージョン 4.0 で追加.

注釈

This configuration is still in experimental

設定ファイルの例

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
root_doc = 'index'

# General information about the project.
project = u'test'
copyright = u'2016, test'
author = u'test'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'test'
# The full version, including alpha/beta/rc tags.
release = u'test'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = u'test vtest'

# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (root_doc, 'test.tex', u'test Documentation',
     u'test', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

# If true, show URL addresses after external links.
#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# If false, no module index is generated.
#
# latex_domain_indices = True


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (root_doc, 'test', u'test Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#
# man_show_urls = False


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (root_doc, 'test', u'test Documentation',
     author, 'test', 'One line description of project.',
     'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False

# -- A random example -----------------------------------------------------

import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']

numfig = True
#language = 'ja'

extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')


autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']