設定¶
設定ディレクトリ には必ず conf.py
が含まれています。このファイルは "ビルド設定ファイル" と呼ばれていて、Sphinxの入出力の動作をカスタマイズするのに必要な(ほとんど)すべての設定はこのファイルに含まれています。この設定ファイルはPythonのプログラムとして書かれています。
An optional file docutils.conf can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.
設定ファイルは、ビルド時にPythonコードとして実行される(設定ファイルが含まれる フォルダをカレントディレクトリに設定し、 execfile()
を使用して呼び出される)ので、任意の複雑なコードを記述できます。Sphinxが読み込む際には単純にファイルの 中の名前空間に定義されている名前を使うことで、設定を読み込みます。
詳細に説明するにあたっての注意点を列挙します。
特別に指定されていない場合には、設定値は文字列型になります。また、指定されていない場合のデフォルト値は空文字列です。
"完全限定名(FQN)"という用語は、モジュール内のインポート可能なPythonオブジェクトをあらわす名前です。例えば、
"sphinx.builders.Builder"
という完全限定名は、sphinx.builders
モジュールにあるBuilder
クラスを意味します。ドキュメント名は、パスのセパレータとして
/
を使用します。また、拡張子は含まないで表記します。Since
conf.py
is read as a Python file, the usual rules apply for encodings and Unicode support.設定の名前空間の内容はpickle化されます(そのため、Sphinxは設定の変更されたのを確認できます)。そのため、pickle化できない値が含まれているのを発見したら、
del
を使って名前空間から削除します。モジュールは自動的に削除されるため、import
したモジュールがあったら、使用後にdel
を行う必要はありません。
プロジェクト情報¶
-
project
¶ ドキュメントを書いているプロジェクト名です。
The author name(s) of the document. The default value is
'unknown'
.
-
copyright
¶
-
project_copyright
¶ '2008, Author Name'
という形式の著作権表記です。バージョン 3.5 で変更: As an alias,
project_copyright
is also allowed.
-
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
¶ The file extensions of source files. Sphinx considers the files with this suffix as sources. The value can be a dictionary mapping file extensions to file types. For example:
source_suffix = { '.rst': 'restructuredtext', '.txt': 'restructuredtext', '.md': 'markdown', }
By default, Sphinx only supports
'restructuredtext'
file type. You can add a new file type using source parser extensions. Please read a document of the extension to know which file type the extension supports.The value may also be a list of file extensions: then Sphinx will consider that they all map to the
'restructuredtext'
file type.Default is
{'.rst': 'restructuredtext'}
.注釈
file extensions have to start with a dot (e.g.
.rst
).バージョン 1.3 で変更: 複数の拡張子をリストで指定出来ます。
バージョン 1.8 で変更: Support file type mapping
-
source_encoding
¶ すべてのreSTのソースファイルのエンコーディングを指定します。デフォルトかつ、推奨のエンコーディングは
'utf-8-sig'
です。バージョン 0.5 で追加: 以前はSphinxはUTF-8エンコードのソースのみ受け付けていました。
-
source_parsers
¶ 必要により、ソースファイルの拡張子に対応するパーサークラスの辞書を指定します。辞書キーには拡張子、値にはパーサークラスあるいはその完全限定名(FQN)が入ります。パーサークラスは
docutils.parsers.Parser
またはsphinx.parsers.Parser
という形式になります。この辞書にない拡張子のファイルに対しては、デフォルトのreStructuredTextパーサーが適用されます。例えば:
source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
注釈
Refer to Markdown for more information on using Markdown with Sphinx.
バージョン 1.3 で追加.
バージョン 1.8 で非推奨: Now Sphinx provides an API
Sphinx.add_source_parser()
to register a source parser. Please use it instead.
-
master_doc
¶ "マスター"ドキュメントのドキュメント名を指定します。"マスター"ドキュメントには、ルートとなる
toctree
ディレクティブが含まれます。デフォルトは'index'
です。バージョン 2.0 で変更: The default is changed to
'index'
from'contents'
.
-
exclude_patterns
¶ globスタイルのパターンのリストを設定し、ソースファイルの探索時に排除すべきファイルを指定します。 1 これらのパターンは、ソースディレクトリからの相対パスで渡されるソースファイル名に対してマッチします。すべての環境で、ディレクトリの指定として、スラッシュ(/)が使用されます。
サンプルのパターン:
'library/xml.rst'
--library/xml.rst
ファイルを無視します。unused_docs
のエントリーの置き換えになります。'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 で追加.
-
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
で、デフォルトのロールは適用されません。デフォルトのロールは、reST標準の
default-role
ディレクティブを使用することによっても個々のドキュメントに対して設定できます。バージョン 0.4 で追加.
-
keep_warnings
¶ If true, keep warnings as "system message" paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when
sphinx-build
is run.デフォルトは
False
で 0.5以前の振る舞いを維持するにはこのままにしてください。バージョン 0.5 で追加.
-
suppress_warnings
¶ 任意の警告メッセージを抑制するときに使う警告の種類のリスト。
Sphinxは以下の警告の種類をサポートしています:
app.add_node
app.add_directive
app.add_role
app.add_generic_role
app.add_source_parser
download.not_readable
image.not_readable
ref.term
ref.ref
ref.numref
ref.keyword
ref.option
ref.citation
ref.footnote
ref.doc
ref.python
misc.highlighting_failure
toc.circular
toc.secnum
epub.unknown_project_files
epub.duplicated_toc_entry
autosectionlabel.*
これらの種類から選択できます。
現状、このオプションが 実験的 な機能であることに注意して下さい。
バージョン 1.4 で追加.
バージョン 1.5 で変更:
misc.highlighting_failure
を追加バージョン 1.5.1 で変更: Added
epub.unknown_project_files
バージョン 1.6 で変更: Added
ref.footnote
バージョン 2.1 で変更: Added
autosectionlabel.*
バージョン 3.3.0 で変更: Added
epub.duplicated_toc_entry
-
needs_sphinx
¶ ドキュメントが想定しているSphinxのバージョンを設定します。
'1.1'
というような形式で、メジャー.マイナー
というバージョン文字列を設定すると、Sphinxは自分のバージョンとの比較を行い、もしもバージョンが古すぎる場合にはビルドを中止します。デフォルトでは、チェックをしないようになっています。バージョン 1.0 で追加.
バージョン 1.4 で変更: マイクロバージョンの文字列も受け取れます。
-
needs_extensions
¶ この値は
extensions
で指定したSphinx拡張に対してバージョン指定する辞書型の値です。例えばneeds_extensions = {'sphinxcontrib.something': '1.5'}
のような形です。このバージョン文字列はmajor.minor
型で指定してください。バージョン指定は全ての拡張に指定する必要はなく、チェックしたいものに対してのみ指定できます。この機能を使うにはSphinx拡張が自分自身のバージョンをSphinxに対し引き渡している必要があります。(設定方法は以下を参考にして下さい Sphinx拡張機能の開発).
バージョン 1.3 で追加.
-
manpages_url
¶ A URL to cross-reference
manpage
directives. If this is defined 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
¶ (タイプ, ターゲット)
というタプルのリスト(デフォルトは空配列)です。nitpickyモードで生成される警告を無視します。タイプ
にはドメイン名入りのものを設定します。('py:func', 'int')
あるいは('envvar', 'LD_LIBRARY_PATH')
といった形式になります。バージョン 1.1 で追加.
-
numfig
¶ If true, figures, tables and code-blocks are automatically numbered if they have a caption. The
numref
role is enabled. Obeyed so far only by HTML and LaTeX builders. Default 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'
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. It requires Docutils 0.14 or later.バージョン 1.6.6 で追加.
-
user_agent
¶ A User-Agent of Sphinx. It is used for a header on HTTP access (ex. linkcheck, intersphinx and so on). Default is
"Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z"
.バージョン 2.3 で追加.
-
tls_verify
¶ If true, Sphinx verifies server certifications. Default is
True
.バージョン 1.5 で追加.
-
tls_cacerts
¶ A path to a certification file of CA or a path to directory which contains the certificates. This also allows a dictionary mapping hostname to the path to certificate file. The certificates are used to verify server certifications.
バージョン 1.5 で追加.
ちなみに
Sphinx uses requests as a HTTP library internally. Therefore, Sphinx refers a certification file on the directory pointed
REQUESTS_CA_BUNDLE
environment variable 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
¶ ドキュメント内でハイライトするデフォルトの言語を設定します。デフォルト値は
'python3'
です。値はPygmentsのlexer名として有効な名前でなければなりません。詳しくは コードサンプルの表示 を参照してください。バージョン 0.5 で追加.
バージョン 1.4 で変更: The default is now
'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. If you prefer Python 2 only highlighting, you can set it back to'python'
.
-
highlight_options
¶ A dictionary that maps language names to options for the lexer modules of Pygments. These are lexer-specific; for the options understood by each, see the Pygments documentation.
サンプル:
highlight_options = { 'default': {'stripall': True}, 'php': {'startinline': True}, }
A single dictionary of options are also allowed. Then it is recognized as options to the lexer specified by
highlight_language
:# configuration for the ``highlight_language`` highlight_options = {'stripall': True}
バージョン 1.3 で追加.
バージョン 3.5 で変更: Allow to configure highlight options for multiple languages
-
pygments_style
¶ Pygmentsがソースコードをハイライトする際に使用するスタイルの名前を設定します。設定しなければ、HTML出力にはテーマのデフォルトスタイルか、
'sphinx'
が選択されます。バージョン 0.3 で変更: 値に独自のPygmentsスタイルクラスの完全修飾名を指定した場合、カスタムスタイルとして使用されます。
-
add_function_parentheses
¶ 関数とメソッドのロールテキストにカッコを付加するかどうかを決めるブール値です。ロールテキストというのは
:func:`input`
のinput
の箇所で、これをTrueにすると、その名前が呼び出し可能オブジェクトであるということが分かるようになります。デフォルトはTrue
です。
-
add_module_names
¶ モジュール定義がされている場所にある、
py:function
などの オブジェクト 名のタイトルのすべてに、モジュール名を付けるかどうかを決めるブール値です。デフォルトはTrue
です。
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 isNone
, which means that no translation will be done.バージョン 0.5 で追加.
バージョン 1.4 で変更: 画像の置き換えをサポートするようになりました。
現在は以下の言語をサポートしています:
ar
-- Arabicbg
-- Bulgarianbn
-- ベンガル語ca
-- カタルーニャ語cak
-- Kaqchikelcs
-- チェコ語cy
-- Welshda
-- デンマーク語de
-- ドイツ語el
-- Greeken
-- 英語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']
です。バージョン 1.5 で変更:
locales
ディレクトリをデフォルト値として使うようになりました。
-
gettext_compact
¶ バージョン 1.1 で追加.
True なら、ドキュメントがトップレベルのプロジェクトファイルだった場合はドキュメントのテキストドメインはそのドキュメント名が使われ、サブディレクトリ以下の場合はサブディレクトリ名が使われます。
If set to string, all document's text domain is this string, making all documents use single text domain.
デフォルトでは
markup/code.rst
というドキュメントはmarkup
テキストドメインとなります。この設定がFalse
の場合、markup/code
となります。バージョン 3.3 で変更: The string value is now accepted.
-
gettext_uuid
¶ もしtrueであれば、SphinxはUUID情報をメッセージカタログの中にバージョントラッキングのために生成します。以下の場合に利用します:
uid行を.potファイルの中の各msgidに追加します。
新しいmsgidと前に保存されたmsgidの類似性を比較計算します。この計算には時間がかかります。
もし計算を速くしたいのであれば、C実装のサードパーティパッケージ
python-levenshtein
を pip install python-levenshtein を使ってインストールしてください。デフォルト値は
False
です。バージョン 1.3 で追加.
-
gettext_location
¶ もしtrueなら、Sphinxはメッセージカタログ内に位置情報を生成します。
デフォルト値は
True
です。バージョン 1.3 で追加.
-
gettext_auto_build
¶ もしtrueであれば、Sphinxは各翻訳カタログファイルについてmoファイルをビルドします。
デフォルト値は
True
です。バージョン 1.3 で追加.
-
gettext_additional_targets
¶ gettextによる抽出を有効化するためにnameを明示し、i18nへ翻訳を適用します。以下のnameが利用できます:
- 索引
インデックスの文字列
- Literal-block
literal blocks (
::
annotation 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.
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 likehttp://example.org/style.css
. The attributes is used for attributes of<link>
tag. It defaults to an empty list.サンプル:
html_css_files = ['custom.css', 'https://example.com/css/custom.css', ('print.css', {'media': 'print'})]
As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer
Sphinx.add_css_files()
.バージョン 1.8 で追加.
バージョン 3.5 で変更: Support priority attribute
-
html_js_files
¶ A list of JavaScript filename. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the
html_static_path
, or a full URI with scheme likehttp://example.org/script.js
. The attributes is used for attributes of<script>
tag. It defaults to an empty list.サンプル:
html_js_files = ['script.js', 'https://example.com/scripts/custom.js', ('custom.js', {'async': 'async'})]
As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer
Sphinx.add_css_files()
.バージョン 1.8 で追加.
バージョン 3.5 で変更: Support priority attribute
-
html_static_path
¶ スタイルシートやスクリプトファイルといった、カスタムの静的ファイル類が含まれるパスのリストです。相対パスが設定されると、conf.pyのあるディレクトリからの相対パスとして処理されます。これらのファイルは、テーマが提供する静的ファイルを
_static
ディレクトリにコピーした後にコピーされるため、default.css
という名前のファイルがあると、テーマで使用するdefault.css
を上書きしてしまうので注意してください。As these files are not meant to be built, they are automatically excluded from source files.
注釈
For security reasons, dotfiles under
html_static_path
will not be copied. If you would like to copy them intentionally, please add each filepath to this setting:html_static_path = ['_static', '_static/.htaccess']
Another way to do that, you can also use
html_extra_path
. It allows to copy dotfiles under the directories.バージョン 0.4 で変更:
html_static_path
で指定されるパスにはサブディレクトリも含めることができます。バージョン 1.0 で変更:
html_static_path
内のエントリーに、単独のファイルを入れることができます。バージョン 1.8 で変更: The files under
html_static_path
are excluded from source files.
-
html_extra_path
¶ robots.txt
や.htaccess
といった、ドキュメントに直接関連しない追加のファイルが含まれるパスのリストです。相対パスが設定されると、conf.pyのあるディレクトリからの相対パスとして処理されます。これらのファイルは出力先ディレクトリにコピーされます。これによって、同名のファイルが既にある場合は上書きされます。As these files are not meant to be built, they are automatically excluded from source files.
バージョン 1.2 で追加.
バージョン 1.4 で変更: The dotfiles in the extra directory will be copied to the output directory. And it refers
exclude_patterns
on copying extra files and directories, and ignores if path matches to patterns.
-
html_last_updated_fmt
¶ If this is not None, a 'Last updated on:' timestamp is inserted at every page bottom, using the given
strftime()
format. The empty string is equivalent to'%b %d, %Y'
(or a locale-dependent equivalent).
-
html_use_smartypants
¶ If true, quotes and dashes are converted to typographically correct entities. Default:
True
.バージョン 1.6 で非推奨: To disable smart quotes, use rather
smartquotes
.
-
html_add_permalinks
¶ Sphinxはそれぞれの見出しに "パーマリンク" を追加します。マウスをそれぞれのリンクの上に持って行くと、パラグラフサインが表示されます。
この値は、パーマリンクのテキストとして使用されます。デフォルトは
"¶"
です。None
を指定すると、パーマリンクは表示されなくなります。バージョン 0.6 で追加: 以前は常に有効になってました。
バージョン 1.1 で変更: 現在では実際に表示されるテキストを文字列で指定します。以前では、ブール型を指定していました。
バージョン 3.5 で非推奨: This has been replaced by
html_permalinks
-
html_permalinks
¶ If true, Sphinx will add "permalinks" for each heading and description environment. Default:
True
.バージョン 3.5 で追加.
-
html_permalinks_icon
¶ A text for permalinks for each heading and description environment. HTML tags are allowed. Default: a paragraph sign;
¶
バージョン 3.5 で追加.
カスタムのサイドバーのテンプレートです。設定値は、ドキュメント名をキーに、テンプレート名を値に持つ辞書として設定します。
キーには、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
¶ もしこの値が空でなかったら、 OpenSearch の説明ファイルが生成され、すべてのページにこのファイルを参照する
<link>
タグが含まれるようになります。OpenSearchが検索ページの位置を示すのに、相対URLをサポートしていないので、この設定値はこれらのドキュメントが提供されるベースのURLにします。最後のスラッシュ(/)は不要です。例えば、Pythonのドキュメントであれば、"https://docs.python.org"
とします。デフォルト値は''
です。
-
html_file_suffix
¶ HTMLファイルを生成するときに、ファイル名の末尾に追加される文字列として使用されます。デフォルトでは
".html"
となります。バージョン 0.4 で追加.
-
html_link_suffix
¶ HTMLファイルに対して生成されるリンクの末尾に付けられる文字列です。デフォルト値としては
html_file_suffix
の値が設定されます。他のウェブサーバのセットアップをサポートする場合などに、別の値を設定できます。バージョン 0.6 で追加.
-
html_show_copyright
¶ もしTrueに設定されると、 "(C) Copyright ..." という文字列をHTMLのフッターに出力します。デフォルトは
True
です。バージョン 1.0 で追加.
-
html_show_sphinx
¶ もしTrueが設定されると、 "このドキュメントは Sphinx で生成しました。" という説明がHTMLのフッターに追加されます。デフォルトは
True
です。バージョン 0.4 で追加.
-
html_output_encoding
¶ HTML出力ファイルのエンコーディングを指定します。デフォルトは
'utf-8'
です。このエンコーディング名Pythonのエンコーディング指定と、HTMLのcharset
の両方で使用できる名前でなければなりません。バージョン 1.0 で追加.
-
html_compact_lists
¶ If true, a list all whose items consist of a single paragraph and/or a sub-list all whose items etc... (recursive definition) will not use the
<p>
element for any of its items. This is standard docutils behavior. Default:True
.バージョン 1.0 で追加.
-
html_secnumber_suffix
¶ セクション番号のサフィックスです。デフォルトは
". "
です。" "
を指定すると、セクション番号の末尾のピリオドが表示されなくなります。バージョン 1.0 で追加.
-
html_search_language
¶ HTMLの全文検索インデックスの生成に使用する言語を設定します。デフォルトは
language
で選択された言語が使用されます。もし、該当する言語のサポートがない場合には、"en"
が選択され、英語処理のアルゴリズムが使用されます。現在では次の言語をサポートしています:
da
-- デンマーク語nl
-- オランダ語en
-- 英語fi
-- フィンランド語fr
-- フランス語de
-- ドイツ語hu
-- ハンガリー語it
-- イタリア語ja
-- 日本語no
-- ノルウェー語pt
-- ポルトガル語ro
-- ローマ語ru
-- ロシア語es
-- スペイン語sv
-- スウェーデン語tr
-- トルコ語zh
-- 中国語
バージョン 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
¶ 真を指定した場合で、'target'オプションか'scale', ’width', 'height' といった拡大縮小オプションが指定されていない場合、画像からオリジナル画像へのリンクが設定されます。デフォルトは
True
です。Document authors can this feature manually with giving
no-scaled-link
class to the image:.. image:: sphinx.png :scale: 50% :class: no-scaled-link
バージョン 1.3 で追加.
バージョン 3.0 で変更: It is disabled for images having
no-scaled-link
class
-
html_math_renderer
¶ The name of math_renderer extension for HTML output. The default is
'mathjax'
.バージョン 1.8 で追加.
-
html_experimental_html5_writer
¶ Output is processed with HTML5 writer. Default is
False
.バージョン 1.6 で追加.
バージョン 2.0 で非推奨.
-
html4_writer
¶ Output is processed with HTML4 writer. Default is
False
.
Options for Single HTML output¶
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, toen
.
-
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, toen
.
-
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出力のオプション¶
これらのオプションを設定すると、epub出力に影響を与えます。このepubビルダーはHTMLビルダーを継承しているため、HTML出力のオプションも適切に反映されます。いくつか、ビルダーへの影響はないが、 ダブリン・コア・メタデータ の中の値として使用される設定値もあります。
-
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
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', u'Cover Page'),)
デフォルト値は
()
です。
-
epub_pre_files
¶ Sphinxによって生成されたテキストの前に追加されるファイル群を指定します。ファイル名とタイトルが組になったタプルを含む配列となります。もしタイトルが空の場合には、
toc.ncx
には追加されません。 サンプル:epub_pre_files = [ ('index.html', 'Welcome'), ]
デフォルト値は
[]
です。
-
epub_post_files
¶ Sphinxによって生成されたテキストの後ろに追加されるファイル群を指定します。ファイル名とタイトルが組になったタプルを含む配列となります。このオプションは、追加のAppendixとして使用されます。もしタイトルが空の場合には、
toc.ncx
には追加されません。デフォルト値は[]
です。
-
epub_exclude_files
¶ buildディレクトリには生成されたりコピーされるが、epubファイルの中には含めないファイルのリストを指定します。デフォルト値は
[]
です。
-
epub_tocdepth
¶ toc.ncx
という目次ファイルに含める、セクションタイトルの階層数を指定します。1以上の数値でなければなりません。デフォルト値は3
です。あまり深いと、ユーザが見て辿るのが難しくなることに注意しましょう。
-
epub_tocdup
¶ このフラグはネストしたtocリストの最初に再びtocエントリーが挿入されたかを確認します。これは章の最初への誘導を簡単に出来ますが、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 master document for your LaTeX build, provide your
master_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_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::
を使って参照しているイメージファイルは、自動的にコピーされます。ファイルの自動コピー時に、ファイル名が衝突しないように設定する必要があります。
バージョン 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 master document for your manual pages build, use your
master_doc
here.)- name
Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).
- description
Description of the manual page. This is used in the NAME section.
- authors
A list of strings with authors, or a single string. Can be an empty string or list if you do not want to automatically generate an AUTHORS section in the manual page.
- section
The manual page section. Used for the output file name as well as in the manual page header.
バージョン 1.0 で追加.
-
man_show_urls
¶ もし
True
が設定されると、リンクのあとにURLのアドレスが追加されます。デフォルトはFalse
です。バージョン 1.1 で追加.
-
man_make_section_directory
¶ If true, make a section directory on build man page. Default is True.
バージョン 3.3 で追加.
バージョン 4.0 で変更: The default is changed to
False
fromTrue
.
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
master_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 で追加.
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_request_headers
¶ A dictionary that maps baseurls to HTTP request headers.
The key is a URL base string like
"https://sphinx-doc.org/"
. To specify headers for other hosts,"*"
can be used. It matches all hosts only when the URL does not match other settings.The value is a dictionary that maps header name to its value.
例:
linkcheck_request_headers = { "https://sphinx-doc.org/": { "Accept": "text/html", "Accept-Encoding": "utf-8", }, "*": { "Accept": "text/html,application/xhtml+xml", } }
バージョン 3.1 で追加.
-
linkcheck_retries
¶ linkcheckビルダーが個々のURLが無効であると判定するまでの試行回数。デフォルトでは1回。
バージョン 1.4 で追加.
-
linkcheck_timeout
¶ A timeout value, in seconds, for the linkcheck builder. The default is to use Python's global socket timeout.
バージョン 1.1 で追加.
-
linkcheck_workers
¶ リンクチェックを行う、ワーカースレッドの数を設定します。デフォルトは5スレッドです。
バージョン 1.1 で追加.
-
linkcheck_anchors
¶ true または false で、リンク中の
#anchor
の有効性をチェックするかどうかを表します。これはドキュメント全体をダウンロードする必要があるので、有効にした場合かなり遅くなります。デフォルトはTrue
です。バージョン 1.2 で追加.
-
linkcheck_anchors_ignore
¶ A list of regular expressions that match anchors Sphinx should skip when checking the validity of anchors in links. This allows skipping anchors that a website's JavaScript adds to control dynamic pages or when triggering an internal REST request. Default is
["^!"]
.注釈
If you want to ignore anchors of a specific page or of pages that match a specific pattern (but still check occurrences of the same page(s) that don't have anchors), use
linkcheck_ignore
instead, for example as follows:linkcheck_ignore = [ 'http://www.sphinx-doc.org/en/1.7/intro.html#' ]
バージョン 1.5 で追加.
-
linkcheck_auth
¶ Pass authentication information when doing a
linkcheck
build.A list of
(regex_pattern, auth_info)
tuples where the items are:- regex_pattern
A regular expression that matches a URI.
- auth_info
Authentication information to use for that URI. The value can be anything that is understood by the
requests
library (see requests Authentication for details).
The
linkcheck
builder will use the first 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 で追加.
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_allow_pre_v3
¶ A boolean (default
False
) controlling whether to parse and try to convert pre-v3 style type directives and type roles.バージョン 3.2 で追加.
バージョン 3.2 で非推奨: Use the directives and roles added in v3.
-
c_warn_on_allowed_pre_v3
¶ A boolean (default
True
) controlling whether to warn when a pre-v3 style type directive/role is parsed and converted.バージョン 3.2 で追加.
バージョン 3.2 で非推奨: Use the directives and roles added in v3.
C++ ドメインのオプション¶
-
cpp_index_common_prefix
¶ A list of prefixes that will be ignored when sorting C++ objects in the global index. For example
['awesome_lib::']
.バージョン 1.5 で追加.
-
cpp_id_attributes
¶ A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been
#define
d for portability.バージョン 1.5 で追加.
-
cpp_paren_attributes
¶ A list of strings that the parser additionally should accept as attributes with one argument. That is, if
my_align_as
is in the list, 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 で追加.
設定ファイルの例¶
# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'test'
copyright = u'2016, test'
author = u'test'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'test'
# The full version, including alpha/beta/rc tags.
release = u'test'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = u'test vtest'
# A shorter title for the navigation bar. Default is the same as html_title.
#
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []
# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None
# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}
# If false, no module index is generated.
#
# html_domain_indices = True
# If false, no index is generated.
#
# html_use_index = True
# If true, the index is split into individual pages for each letter.
#
# html_split_index = False
# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'test.tex', u'test Documentation',
u'test', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None
# If true, show page references after internal links.
#
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
#
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
#
# latex_appendices = []
# If false, no module index is generated.
#
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'test', u'test Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'test', u'test Documentation',
author, 'test', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []
# If false, no module index is generated.
#
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False
# -- A random example -----------------------------------------------------
import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']
numfig = True
#language = 'ja'
extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')
autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']