設定¶
設定ディレクトリ には必ず 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
を行う必要はありません。
プロジェクト情報¶
- 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.
- version¶
主要なプロジェクトのバージョンです。 置換構文を使って
|version|
このように書きます。例えば、Pythonのドキュメントであれば、これは2.6
になります。
一般的な設定¶
- 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.
- 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
frommaster_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 thelibrary/xml.rst
file'library/xml'
-- ignores thelibrary/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 thelibrary/xml
directory'library/xml*'
-- all files and directories starting withlibrary/xml
'**/doc'
-- alldoc
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 adefault-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
andtoc.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 tohttps://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 thattype
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 thetype
andtarget
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 isFalse
.注釈
このオプションを有効にしていてもいなくても、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 at1
.if
1
(default) numbers will bex.1
,x.2
, ... withx
the section number (top level sectioning; nox.
if no section). This naturally applies only if section numbering has been activated via the:numbered:
option of thetoctree
directive.2
means that numbers will bex.y.1
,x.y.2
, ... if located in a sub-section (but stillx.1
,x.2
, ... if located directly under a section and1
,2
, ... if not in any top level section.)etc...
バージョン 1.3 で追加.
バージョン 1.7 で変更: The LaTeX builder obeys this setting (if
numfig
is set toTrue
).
- 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 exceptman
andtext
(seesmartquotes_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, thensmartquotes
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, amake text
followingmake html
needs to be issued in the formmake 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 usemake
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 iftls_cacerts
not set.
- today¶
- today_fmt¶
これらの値は現在の日付をどのようにフォーマットするのか、というものを決めます。これは
|today|
を置き換える時に使用されます。もし
today
に空ではない値が設定されたらそれが使用されます。そうでない場合には、
today_fmt
で与えられたフォーマットを使い、time.strftime()
で生成された値が使用されます。
The default is now
today
and atoday_fmt
of'%b %d, %Y'
(or, if translation is enabled withlanguage
, 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 showClass.method()
andfunction()
, leaving out themodule.
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 toTrue
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 byfigure_language_filename
(e.g. the German version ofmyfigure.png
will bemyfigure.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
-- Arabicbg
-- Bulgarianbn
-- ベンガル語ca
-- カタルーニャ語cak
-- Kaqchikelcs
-- チェコ語cy
-- Welshda
-- デンマーク語de
-- ドイツ語el
-- Greeken
-- English (default)eo
-- Esperantoes
-- スペイン語et
-- エストニア語eu
-- バスク語fa
-- イラン語fi
-- フィンランド語fr
-- フランス語he
-- ヘブライ語hi
-- Hindihi_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
-- Albaniansr
-- Serbiansr@latin
-- Serbian (Latin)sr_RS
-- Serbian (Cyrillic)sv
-- スウェーデン語ta
-- Tamilte
-- Telugutr
-- トルコ語uk_UA
-- ウクライナ語ur
-- Urduvi
-- ベトナム語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 andcode-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 todirname/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 todirname/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
: addtranslated
anduntranslated
classes to all nodes with translatable content.translated
: only add thetranslated
class.untranslated
: only add theuntranslated
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
.
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 likehttps://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 likehttps://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 -- 前のドキュメントと、次のドキュメントへの2つのリンク
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回作成されます。一つ目は全てのエントリーを含む索引です。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 defaultNone
, 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
-- 中国語
バージョン 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 orNone
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 ashtml_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_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 ofapplehelp_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 ofindex.html
for an English speaking customer, it will look athttps://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 theAHLookupAnchor
function or theopenHelpAnchor:inBook:
method in your code. It also allows you to usehelp: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’sResources
, 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, orNone
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_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 theproject
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_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エントリーが挿入されたかを確認します。これは章の最初への誘導を簡単に出来ますが、1つのリストの異なるエントリーを混同するため混乱する可能性があります。デフォルト値は
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 iflanguage
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 thelatex_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 packagexeCJK
) 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 addr'\usepackage{unicode-math}'
(e.g. via thelatex_elements
'preamble'
key). You may preferr'\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
orFalse
. 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 isNone
; the topmost sectioning unit is switched by documentclass:section
is used if documentclass will behowto
, otherwisechapter
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
forhowto
.)バージョン 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 thetabularcolumns
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 usingtabulary
.バージョン 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 arebooktabs
,borderless
,standard
,colorrows
,nocolorrows
. The latter two can be combined with any of the first three. Thestandard
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 (seetabularcolumns
). 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 thebooktabs
class, but it will be necessary to addr'\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 (fromindex
usage). This means that words with UTF-8 characters will get ordered correctly for thelanguage
.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'
butTrue
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 bysphinx-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
andhowto
are bundled.manual
A LaTeX theme for writing a manual. It imports the
report
document class (Japanese documents usejsbook
).howto
A LaTeX theme for writing an article. It imports the
article
document class (Japanese documents usejreport
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
fromTrue
.バージョン 4.0.2 で変更: The default is changed to
True
fromFalse
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
orFalse
. 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 で追加.
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 isTrue
.バージョン 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_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'
.
リンクチェックビルダーのオプション¶
- 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 matchingauth_info
value it can find in thelinkcheck_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 thelinkcheck_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 で追加.
脚注
"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, thenmy_align_as(X)
is parsed as an attribute for all stringsX
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, thenmy_align_as(X)
is parsed as an attribute for all stringsX
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, defaultFalse
.サンプル¶
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']