設定¶

設定ディレクトリには必ず 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.

The configuration file is executed as Python code at build time (using importlib.import_module(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file's namespace as its configuration.

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

特別に指定されていない場合には、設定値は文字列型になります。また、指定されていない場合のデフォルト値は空文字列です。
"完全限定名(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'.

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

バージョン 7.1 で変更: The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line.

project_copyright¶: 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¶

ソースファイルのファイル拡張子です。 Sphinx は、この拡張子を持つファイルをソースと見なします。値は、ファイル拡張子をファイルタイプにマッピングする辞書を取りえます。例えば

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

デフォルトでは、Sphinx は 'restructuredtext' ファイルタイプのみをサポートします。ソースパーサー拡張機能を使用して、新しいファイルタイプを追加できます。拡張機能のドキュメントを読んで、拡張機能がサポートするファイルタイプを確認してください。

値は、ファイル拡張子のリストの場合もあります: その場合 Sphinx はそれらをすべて 'restructuredtext' ファイルタイプにマップするものと見なします。

デフォルト値は {'.rst': 'restructuredtext'} です。

注釈

ファイル拡張子はドットで始まる必要があります (例: .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¶

A list of glob-style patterns [1] that should be excluded when looking for source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.

サンプルのパターン:

'library/xml.rst' -- ignores the library/xml.rst file
'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 で追加.

include_patterns¶

A list of glob-style patterns [1] that are used to find source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms. The default is **, meaning that all files are recursively included from the source directory.

サンプルのパターン:

'**' -- all files in the source directory and subdirectories, recursively
'library/xml' -- just the library/xml directory
'library/xml*' -- all files and directories starting with library/xml
'**/doc' -- all doc directories (this might be useful if documentation is co-located with source files)

バージョン 5.1 で追加.

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 で、デフォルトのロールは適用されません。

The default role can always be set within individual documents using the standard reST default-role directive.

バージョン 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
autosectionlabel.*
download.not_readable
epub.unknown_project_files
epub.duplicated_toc_entry
i18n.inconsistent_references
index
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.excluded
toc.not_readable
toc.secnum

You can choose from these types. You can also give only the first component to exclude all warnings attached to it.

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

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

バージョン 4.3 で変更: Added toc.excluded and toc.not_readable

バージョン 4.5 で追加:

Added i18n.inconsistent_references

バージョン 7.1 で追加: Added index warning type.

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 Extensions API).

バージョン 1.3 で追加.

manpages_url¶

A URL to cross-reference manpage roles. 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¶: A set or list of (type, target) tuples (by default empty) that should be ignored when generating warnings in "nitpicky mode". Note that type should include the domain name if present. Example entries would be ('py:func', 'int') or ('envvar', 'LD_LIBRARY_PATH').

バージョン 1.1 で追加.

バージョン 6.2 で変更: Changed allowable container types to a set, list, or tuple

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 で追加.

バージョン 6.2 で変更: Changed allowable container types to a set, list, or tuple

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 %s' 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.

バージョン 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 で追加.

Tip

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スタイルクラスの完全修飾名を指定した場合、カスタムスタイルとして使用されます。

maximum_signature_line_length¶

If a signature's length in characters exceeds the number set, each parameter within the signature will be displayed on an individual logical line.

When None (the default), there is no maximum length and the entire signature will be displayed on a single logical line.

A 'logical line' is similar to a hard line break---builders or themes may choose to 'soft wrap' a single logical line, and this setting does not affect that behaviour.

Domains may provide options to suppress any hard wrapping on an individual object directive, such as seen in the C, C++, and Python domains (e.g. py:function:single-line-parameter-list).

バージョン 7.1 で追加.

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

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

toc_object_entries¶: Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.). Default is True.

toc_object_entries_show_parents¶

A string that determines how domain objects (e.g. functions, classes, attributes, etc.) are displayed in their table of contents entry.

Use domain to allow the domain to determine the appropriate number of parents to show. For example, the Python domain would show Class.method() and function(), leaving out the module. level of parents. This is the default setting.

Use hide to only show the name of the element without any parents (i.e. method()).

Use all to show the fully-qualified name for the object (i.e. module.Class.method()), displaying all parents.

バージョン 5.2 で追加.

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 で追加.

option_emphasise_placeholders¶: Default is False. When enabled, emphasise placeholders in option directives. To display literal braces, escape with a backslash (\{). For example, option_emphasise_placeholders=True and .. option:: -foption={TYPE} would render with TYPE emphasised.

バージョン 5.1 で追加.

国際化のオプション¶

これらのオプションは、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 'en'.

バージョン 0.5 で追加.

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

バージョン 5.0 で変更.

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

ar -- Arabic
bg -- Bulgarian
bn -- ベンガル語
ca -- カタルーニャ語
cak -- Kaqchikel
cs -- チェコ語
cy -- Welsh
da -- デンマーク語
de -- ドイツ語
el -- Greek
en -- English (default)
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_allow_fuzzy_translations¶: If true, "fuzzy" messages in the message catalogs are used for translation. The default is False.

バージョン 4.3 で追加.

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.

translation_progress_classes¶

Control which, if any, classes are added to indicate translation progress. This setting would likely only be used by translators of documentation, in order to quickly indicate translated and untranslated content.

True: add translated and untranslated classes to all nodes with translatable content.
translated: only add the translated class.
untranslated: only add the untranslated class.
False: do not add any classes to indicate translation progress.

デフォルト値は False です。

バージョン 7.1 で追加.

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 で追加.

html_logo¶: 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_file().

バージョン 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_file().

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

html_permalinks¶: Add link anchors for each heading and description environment. Default: True.

バージョン 3.5 で追加.

html_permalinks_icon¶: Text for link anchors for each heading and description environment. HTML entities and Unicode 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_show_sourcelink¶: html_copy_source がTrueに設定されていて、かつ、この設定値もTrueに設定された場合に、サイドバーにreSTのソースファイルへのリンクを表示します。デフォルト値は True です。

バージョン 0.6 で追加.

html_sourcelink_suffix¶: 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¶: This is the file name suffix for generated HTML files, if set to a str value. If left to the default None, the suffix will be ".html".

バージョン 0.4 で追加.

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

バージョン 0.6 で追加.

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

バージョン 1.0 で追加.

html_show_search_summary¶: If true, the text around the keyword is shown as summary of each search result. Default is True.

バージョン 4.5 で追加.

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言語での実装を使用できます。

PorterStemmer (en)
PyStemmer (all languages)

バージョン 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 で追加.

html_scaled_image_link¶

If true, image itself links to the original image if it doesn't have 'target' option or scale related options: 'scale', 'width', 'height'. The default is True.

Document authors can disable 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 で追加.

htmlhelp_link_suffix¶: 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.

epub_copyright¶: ドキュメントの著作権表示です。デフォルトでは 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', '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.

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要素のタプルも指定できます。

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

A list of styling classes (strings). Currently supported:

'booktabs': no vertical lines, and only 2 or 3 horizontal lines (the latter if there is a header), using the booktabs package.
'borderless': no lines whatsoever.
'colorrows': the table rows are rendered with alternating background colours. The interface to customize them is via dedicated keys of The sphinxsetup configuration setting.

重要

With the 'colorrows' style, the \rowcolors LaTeX command becomes a no-op (this command has limitations and has never correctly supported all types of tables Sphinx produces in LaTeX). Please update your project to use instead the latex table color configuration keys.

Default: ['booktabs', 'colorrows']

バージョン 5.3.0 で追加.

バージョン 6.0.0 で変更: Modify default from [] to ['booktabs', 'colorrows'].

Each table can override the global style via :class: option, or .. rst-class:: for no-directive tables (cf. テーブル). Currently recognized classes are booktabs, borderless, standard, colorrows, nocolorrows. The latter two can be combined with any of the first three. The standard class produces tables with both horizontal and vertical lines (as has been the default so far with Sphinx).

A single-row multi-column merged cell will obey the row colour, if it is set. See also TableMergeColor{Header,Odd,Even} in the The sphinxsetup configuration setting section.

注釈

It is hard-coded in LaTeX that a single cell will obey the row colour even if there is a column colour set via \columncolor from a column specification (see tabularcolumns). Sphinx provides \sphinxnorowcolor which can be used like this:
```
>{\columncolor{blue}\sphinxnorowcolor}
```
in a table column specification.
Sphinx also provides \sphinxcolorblend which however requires the xcolor package. Here is an example:
```
>{\sphinxcolorblend{!95!red}}
```
It means that in this column, the row colours will be slightly tinted by red; refer to xcolor documentation for more on the syntax of its \blendcolors command (a \blendcolors in place of \sphinxcolorblend would modify colours of the cell contents, not of the cell background colour panel...). You can find an example of usage in the 非推奨 API section of this document in PDF format.

ヒント

If you want to use a special colour for the contents of the cells of a given column use >{\noindent\color{<color>}}, possibly in addition to the above.
Multi-row merged cells, whether single column or multi-column currently ignore any set column, row, or cell colour.
It is possible for a simple cell to set a custom colour via the raw directive and the \cellcolor LaTeX command used anywhere in the cell contents. This currently is without effect in a merged cell, whatever its kind.

ヒント

In a document not using 'booktabs' globally, it is possible to style an individual table via the booktabs class, but it will be necessary to add r'\usepackage{booktabs}' to the LaTeX preamble.

On the other hand one can use colorrows class for individual tables with no extra package (as Sphinx since 5.3.0 always loads colortbl).

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:: を使って参照しているイメージファイルは、自動的にコピーされます。

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

注意

Filenames with extension .tex will automatically be handed over to the PDF build process triggered by sphinx-build -M latexpdf or by make latexpdf. If the file was added only to be \input{} from a modified preamble, you must add a further suffix such as .txt to the filename and adjust accordingly the \input{} command added to the LaTeX document preamble.

バージョン 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. Can be an empty string if you do not want to automatically generate 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 で追加.

texinfo_cross_references¶: If false, do not generate inline references in a document. That makes an info file more readable with stand-alone reader (info). Default is True.

バージョン 4.4 で追加.

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_allowed_redirects¶

A dictionary that maps a pattern of the source URI to a pattern of the canonical URI. The linkcheck builder treats the redirected link as "working" when:

the link in the document matches the source URI pattern, and
the redirect location matches the canonical URI pattern.

例:

linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

If set, linkcheck builder will emit a warning when disallowed redirection found. It's useful to detect unexpected redirects under the warn-is-error mode.

バージョン 4.1 で追加.

linkcheck_request_headers¶

A dictionary that maps baseurls to HTTP request headers.

The key is a URL base string like "https://www.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://www.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 ["^!"].

Tip

Use linkcheck_anchors_ignore_for_url to check a URL, but skip verifying that the anchors exist.

注釈

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_anchors_ignore_for_url¶: A list or tuple of regular expressions matching URLs for which Sphinx should not check the validity of anchors. This allows skipping anchor checks on a per-page basis while still checking the validity of the page itself. Default is an empty tuple ().

バージョン 7.1 で追加.

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 で追加.

linkcheck_exclude_documents¶

A list of regular expressions that match documents in which Sphinx should not check the validity of links. This can be used for permitting link decay in legacy or historical sections of the documentation.

サンプル:

# ignore all links in documents located in a subfolder named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

バージョン 4.4 で追加.

XML出力のオプション¶

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

バージョン 1.2 で追加.

脚注

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_extra_keywords¶: A list of identifiers to be recognized as keywords by the C parser. It defaults to ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local'].

バージョン 4.0.3 で追加.

c_maximum_signature_line_length¶: If a signature's length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

バージョン 7.1 で追加.

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 で追加.

cpp_maximum_signature_line_length¶: If a signature's length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

バージョン 7.1 で追加.

Options for the Python domain¶

python_display_short_literal_types¶

This value controls how Literal types are displayed. The setting is a boolean, default False.

サンプル¶

The examples below use the following py:function directive:

.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

When False, Literal types display as per standard Python syntax, i.e.:

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

When True, Literal types display with a short, PEP 604-inspired syntax, i.e.:

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

バージョン 6.2 で追加.

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

python_maximum_signature_line_length¶

If a signature's length in characters exceeds the number set, each argument or type parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

For the Python domain, the signature length depends on whether the type parameters or the list of arguments are being formatted. For the former, the signature length ignores the length of the arguments list; for the latter, the signature length ignores the length of the type parameters list.

For instance, with python_maximum_signature_line_length = 20, only the list of type parameters will be wrapped while the arguments list will be rendered on a single line

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

バージョン 7.1 で追加.

Options for the Javascript domain¶

javascript_maximum_signature_line_length¶: If a signature's length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

バージョン 7.1 で追加.

設定ファイルの例¶

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module 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 = 'test'
copyright = '2016, test'
author = '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 = 'test'
# The full version, including alpha/beta/rc tags.
release = '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 = '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', 'test Documentation',
     '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', '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', '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

# If false, do not generate in manual @ref nodes.
#
# texinfo_cross_references = 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']

On this page

Site navigation

設定¶

プロジェクト情報¶

一般的な設定¶

国際化のオプション¶

Options for Math¶

HTML出力のオプション¶

Options for Single HTML output¶

Options for HTML help output¶

AppleHelp出力のオプション¶

epub出力のオプション¶

LaTeX出力のオプション¶

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

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

Texinfo出力のオプション¶

Options for QtHelp output¶

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

XML出力のオプション¶

Options for the C domain¶

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

Options for the Python domain¶

サンプル¶

Options for the Javascript domain¶

設定ファイルの例¶