ビルド設定ファイル(conf.py)

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

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

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

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

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

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

  • conf.py はPythonファイルとして読み込むため、Pythonの標準のエンコーディングや、ユニコードサポートなどを利用できます。設定値にASCII文字以外の文字を含む場合には、エンコーディング宣言(行頭に # -*- coding: utf-8 -*- とコメントを入れる)を使用して、ユニコード文字列リテラルを使用してください。

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

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

一般的な設定

extensions

使用したい Sphinx拡張 のモジュールを指定する配列です。この設定自体は配列で、中に、使用したい拡張モジュールの名前の文字列が含まれます。文字列としてはSphinxに付属のもの( sphinx.ext.* )か、カスタムの拡張機能を指定できます。

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

import sys, os

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

extensions = ['extname']

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

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

source_suffix

ソースファイルに付く、ファイル名の拡張子、または拡張子のリストを指定します。ここで指定された名前が末尾に付くファイルだけがソースファイルとして読み込まれます。デフォルトは '.rst' です。

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

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'}

注釈

Read more about how to use Markdown with Sphinx at Markdown support.

バージョン 1.3 で追加.

master_doc

“マスター”ドキュメントのドキュメント名を指定します。”マスター”ドキュメントには、ルートとなる toctree ディレクティブが含まれます。デフォルトは 'contents' です。

exclude_patterns

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

サンプルのパターン:

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

  • 'library/xml'library/xml ディレクトリを無視します。 exclude_trees のエントリーの置き換えになります。

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

  • '**/.svn' – すべての .svn ディレクトリを無視します。 exclude_dirnames のエントリーの置き換えになります。

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

バージョン 1.0 で追加.

templates_path

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

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

template_bridge

TemplateBridge のインスタンスを返す、呼び出し可能なオブジェクト、もしくはシンプルなクラスをあらわす完全限定名です。このインスタンスはHTMLドキュメントや、その他のビルダーの出力をレンダリングする際に使用されます。現在ではchanges builderに使用されています。テンプレートブリッジはHTMLテーマが使用された場合には、これに対応するように作られるべきです。

rst_epilog

読み込まれたすべてのソースファイルの末尾に挿入されるreSturucturedTextの文字列を設定します。この設定を利用すると、文字列置換をすべてのファイルに対して行いたいときに、うまく動作します:

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

バージョン 0.6 で追加.

rst_prolog

読み込まれたすべてのソースファイルの先頭に挿入されるreSturucturedTextの文字列を設定します。

バージョン 1.0 で追加.

primary_domain

デフォルトの ドメイン を指定します。 None を設定すると、デフォルトドメインを無効にします。デフォルトは 'py' です。ドメイン名が明示的に与えられるか、 default-domain ディレクティブで指定するかに関わらず、他のドメインのオブジェクトにはドメイン名が明示的に付加されるでしょう。たとえば、デフォルトのドメインがCであれば、Pythonの関数は単なる”関数”ではなく、”Python関数”という名前になります。

バージョン 1.0 で追加.

default_role

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

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

バージョン 0.4 で追加.

keep_warnings

Trueが設定されると、警告の内容がビルド済みドキュメントの”システムメッセージ”パラグラフの中に保存されます。この設定に関係なく、 sphinx-build 実行時標準エラー出力には警告が出力されます。

デフォルトは 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
  • image.data_uri
  • image.nonlocal_uri
  • ref.term
  • ref.ref
  • ref.numref
  • ref.keyword
  • ref.option
  • ref.citation
  • ref.doc
  • misc.highlighting_failure
  • toc.secnum
  • epub.unknown_project_files

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

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

バージョン 1.4 で追加.

バージョン 1.5 で変更: Added misc.highlighting_failure

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

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

nitpicky

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

バージョン 1.0 で追加.

nitpick_ignore

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

バージョン 1.1 で追加.

numfig

Trueの場合、キャプションのある図、表、コードブロックに自動的に番号付けされます。それと同時に numref ロールが有効になります。このオプションはいまのところHTMLビルダーとLaTeXビルダーでのみ動作します。デフォルトは False です。

注釈

The LaTeX builder always assigns numbers whether this option is enabled or not.

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

図表番号のスコープです。スコープ指定によって、numfig機能が番号付けする範囲を決めます。 0 は全てのドキュメントで通し番号を使います。 1 はセクション毎の番号付けで、x.1, x.2, x.3, ...のように付与します。 2 はサブセクション毎の番号付けで、x.x.1, x.x.2, x.x.3, ...のように付与します。デフォルトは 1 です。

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

プロジェクト情報

project

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

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

version

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

release

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

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

today
today_fmt

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

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

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

デフォルトでは today は空で today_fmt には '%B %d, %Y' という値が設定されています(もしも language が設定され、翻訳機能が有効になっている場合には、選択された言語の %format が使用されます)。

バージョン 1.4 で変更: 時刻フォーマットの形式がstrftime対応からLocale Data Markup Languageになりました。後方互換性の為、strftime対応形式もSphinx-1.5までサポートされます。

バージョン 1.4.1 で変更: 時刻フォーマットの形式がLocale Data Markup Languageから再びstrftimeになりました。後方互換性の為、LDML対応形式もSphinx-1.5までサポートされます。

highlight_language

ドキュメント内でハイライトするデフォルトの言語を設定します。デフォルト値は 'python3' です。値はPygmentsのlexer名として有効な名前でなければなりません。詳しくは コードサンプルの表示 を参照してください。

バージョン 0.5 で追加.

バージョン 1.4 で変更: デフォルト値は 'default' となりました。これは 'python3' に似ています; これはほぼ 'python' の上位互換です。しかし、ハイライトに失敗した場合、警告を出さずに 'none' へ巻き戻ります。 'python3' や他の言語でハイライトに失敗した場合は、警告が出されます。もしもPython 2だけをハイライトしたい場合、 'python' を指定することもできます。

highlight_options

辞書型の値で、 highlight_language で指定されたlexerが、どのようにハイライトするかを調整するオプションです。この値はlexerによって異なります。それぞれどのようなオプションを指定出来るかは Pygments documentation を参照してください。

バージョン 1.3 で追加.

pygments_style

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

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

add_function_parentheses

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

add_module_names

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

show_authors

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

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> も削除対象にしました。

国際化のオプション

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

language

ドキュメントの言語のコードです。Sphinxが自動的に生成する文章が、その言語で出力されるようになります。また、Sphinxは locale_dirs で設定される翻訳セットを使って、ドキュメントのパラグラフをそれぞれ置き換えようとします。Sphinxは figure_language_filename で名付けられた言語特有の文字を探し、その文字を元の文字の代わりに使います。LaTeXビルダーでは Babel パッケージのオプションとして、適切な言語が選択されます。デフォルトは None で翻訳はされません(訳注: 英語で出力されます)

バージョン 0.5 で追加.

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

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

  • bn – ベンガル語

  • ca – カタルーニャ語

  • cs – チェコ語

  • da – デンマーク語

  • de – ドイツ語

  • en – 英語

  • es – スペイン語

  • et – エストニア語

  • eu – バスク語

  • fa – イラン語

  • fi – フィンランド語

  • fr – フランス語

  • he – ヘブライ語

  • hr – クロアチア語

  • hu – ハンガリー語

  • id – インドネシア

  • it – イタリア語

  • ja – 日本語

  • ko – 韓国語

  • lt – リトアニア語

  • lv – ラトビア語

  • mk – マケドニア語

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

  • ne – ネパール語

  • nl – オランダ語

  • pl – ポーランド語

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

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

  • ru – ロシア語

  • si – シンハラ語

  • sk – スロバキア語

  • sl – スロベニア語

  • sv – スウェーデン語

  • tr – トルコ語

  • uk_UA – ウクライナ語

  • vi – ベトナム語

  • zh_CN – 簡体字中国語

  • zh_TW – 繁体字中国語

locale_dirs

バージョン 0.5 で追加.

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

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

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

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

gettext_compact

バージョン 1.1 で追加.

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

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

gettext_uuid

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

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

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

もし計算を速くしたいのであれば、C実装のサードパーティパッケージ python-levenshteinpip 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:

リテラルブロック: ::code-block.

Doctest-block:

doctestブロック

Raw:

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

Image:

imageとfigureのuriとalt

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

デフォルトは [] です。

バージョン 1.3 で追加.

figure_language_filename

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

  • {root} - the filename, including any path component, without the file extension, e.g. dirname/filename
  • {path} - the directory path component of the filename, with a trailing slash if non-empty, e.g. dirname/
  • {basename} - the filename without the directory path or file extension components, e.g. filename
  • {ext} - the file extension, e.g. .png
  • {language} - the translation language, e.g. en

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

バージョン 1.4 で追加.

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

HTML出力のオプション

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

html_theme

HTML出力煮使用される “テーマ” です。 section about theming を参照して下さい。デフォルトは '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

HTMLドキュメントの短いタイトルを設定します。これはヘッダ内のリンク、HTMLヘルプのドキュメントで使用されます。設定されない場合には、 html_title と同じ値がデフォルトで使用されます。

バージョン 0.4 で追加.

html_context

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

バージョン 0.5 で追加.

もし設定されると、ドキュメントのロゴ画像のファイル名として使用されます(パスは configuration directory からの相対パスです)。これはサイドバーの最上部に置かれます。そのため、200ピクセルを超えてはいけません。デフォルト値は None です。

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

html_favicon

もし設定されると、ドキュメントのfavicon画像のファイル名として使用されます(パスは configuration directory からの相対パスです)。このアイコンは最近のブラウザではタブ、ウィンドウ、ブックマークに使われます。これはWindowsのアイコンファイル形式(.ico)で、16x16か32x32の大きさでなければいけません。デフォルト値は None です。

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

html_static_path

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

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

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

html_extra_path

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

これらのファイルは自動的に exclude_patterns に追加され、ビルドの対象にはなりません。

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

バージョン 1.4 で変更: 時刻フォーマットの形式がstrftime対応からLocale Data Markup Languageになりました。後方互換性の為、strftime対応形式もSphinx-1.5までサポートされます。

バージョン 1.4.1 で変更: 時刻フォーマットの形式がLocale Data Markup Languageから再びstrftimeになりました。後方互換性の為、LDML対応形式もSphinx-1.5までサポートされます。

html_use_smartypants

trueの場合、 SmartyPants がクオートおよびダッシュのタイポしたエンティティを訂正する変換に使われます。

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

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

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

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

html_sidebars

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

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

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

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

    デフォルトサイドバー(どのパターンにもマッチしなかったドキュメントで使用される)としては、以下の設定がされたものとして動作します: ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'].

  • もしも値が文字列だった場合には、指定されたカスタムサイドバーが、 'sourcelink.html''searchbox.html' の間に追加されます。これは、Sphinxの1.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スタイルのキーが利用できるようになり、複数のサイドバーが設定できるようになりました。

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

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_modindex

もしTrueに設定されると、HTMLドキュメントにモジュールの索引を挿入します。デフォルトは True です。

バージョン 1.0 で撤廃: html_domain_indices を使用して下さい。

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 です。

警告

もしもこの設定値が False に設定されると、 JavaScriptの検索機能を使用したときに、マッチしたドキュメントのタイトルしか表示できなくなります。マッチした文章の内容を表示することはできません。

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

バージョン 0.6 で追加.

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

バージョン 1.5 で追加.

html_use_opensearch

もしこの値が空でなかったら、 OpenSearch <http://opensearch.org/Home> _ の説明ファイルが生成され、すべてのページにこのファイルを参照する <link> タグが含まれるようになります。OpenSearchが検索ページの位置を示すのに、相対URLをサポートしていないので、この設定値はこれらのドキュメントが提供されるベースのURLにします。最後のスラッシュ(/)は不要です。例えば、Pythonのドキュメントであれば、 "https://docs.python.org" とします。デフォルト値は '' です。

html_file_suffix

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

バージョン 0.4 で追加.

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

バージョン 0.6 で追加.

html_translator_class

HTML変換クラスへの完全限定名(FQN)を表す文字列です。これはSphinxの HTMLTranslator のサブクラスです。これはドキュメントツリーをHTMLに変換するのに使用されます。デフォルト値は None で、組み込みのトランスレータが使用されます。

バージョン 1.5 で撤廃: Implement your translator as extension and use Sphinx.set_translator instead.

もし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

Trueに設定すると、1つのパラグラフのみを含むリストのアイテムは <p> エレメントを使ってレンダリングされなくなります。これは標準のdocutilsの振る舞いと同じです。デフォルト値は True です。

バージョン 1.0 で追加.

html_secnumber_suffix

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

バージョン 1.0 で追加.

html_search_language

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

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

  • da – デンマーク語

  • nl – オランダ語

  • en – 英語

  • fi – フィンランド語

  • fr – フランス語

  • de – ドイツ語

  • hu – ハンガリー語

  • it – イタリア語

  • ja – 日本語

  • no – ノルウェー語

  • pt – ポルトガル語

  • ro – ローマ語

  • ru – ロシア語

  • es – スペイン語

  • sv – スウェーデン語

  • tr – トルコ語

  • zh – 中国語

ビルドスピードの向上

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

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

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

html_search_options

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

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

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

のデータ型:

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

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

‘sphinx.search.ja.DefaultSplitter’:
 

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

‘sphinx.search.ja.MeCabSplitter’:
 

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

‘sphinx.search.ja.JanomeSplitter’:
 

Janomeバインディング。この分かち書きアルゴリズムを使うには、 Janome が必要です。

互換性を維持するために、 'mecab''janome''default' も指定可能です。しかし、Sphinx-1.6以降廃止予定です。

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

'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 optionuser_dic オプションで設定されたユーザー辞書ファイルのエンコーディングです。デフォルト値は ‘utf8’ です。

バージョン 1.1 で追加.

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

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

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

html_search_scorer

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

バージョン 1.2 で追加.

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

バージョン 1.3 で追加.

htmlhelp_basename

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

AppleHelp出力のオプション

バージョン 1.3 で追加.

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

注釈

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

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

applehelp_bundle_name

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

applehelp_bundle_id

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

警告

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

applehelp_dev_region

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

applehelp_bundle_version

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

applehelp_icon

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

applehelp_kb_product

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

applehelp_kb_url

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

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

applehelp_remote_url

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

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

Defaults to None for no remote content.

applehelp_index_anchors

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

applehelp_min_term_length

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

applehelp_stopwords

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

言語

コード

English en
German de
Spanish es
French fr
Swedish sv
Hungarian hu
Italian it

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

applehelp_locale

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

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

applehelp_title

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

applehelp_codesign_identity

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

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

applehelp_codesign_flags

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

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

applehelp_indexer_path

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

applehelp_codesign_path

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

applehelp_disable_external_tools

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

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

デフォルト値は False です。

epub出力のオプション

これらのオプションを設定すると、epub出力に影響を与えます。このepubビルダーはHTMLビルダーを継承しているため、HTML出力のオプションも適切に反映されます。いくつか、ビルダーへの影響はないが、 ダブリン・コア・メタデータ の中の値として使用される設定値もあります。

epub_basename

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

epub_theme

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

epub_theme_options

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

バージョン 1.2 で追加.

epub_title

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

epub_description

ドキュメントの説明です。デフォルト値は '' です。

バージョン 1.4 で追加.

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

epub_author

ドキュメントの著者名です。この設定値はダブリン・コア・メタデータの中に出力されます。デフォルト値は 'unknown' です。

epub_contributor

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

バージョン 1.4 で追加.

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

epub_language

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

epub_publisher

ドキュメントの出版社情報になります。この設定値はダブリン・コア・メタデータの中に出力されます。プロジェクトのホームページなど、なんらかの意味のある文字列を入れることになるでしょう。デフォルト値は 'unknown' です。

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

epub_identifier

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

epub_scheme

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

epub_uid

ドキュメントのユニークな識別子です。この設定値はダブリン・コア・メタデータの中に出力されます。ランダムな文字列を使うことが出来ます。デフォルト値は '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_guide

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

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 です。

注釈

epub3 builder ignores epub_tocdup option(always False)

epub_tocscope

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

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

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

バージョン 1.2 で追加.

epub_fix_images

このフラグは、いくつかの epub リーダでサポートされない画像形式を Sphinx が修正しようとするべきかどうかを決定します。そのときには、小さな色テーブルを持つパレット画像はアップグレードされます。このオプションを使用するためには Python Image Library (PIL) をインストールする必要があります。自動変換が情報を失うかもしれないので、デフォルト値は False です。

バージョン 1.2 で追加.

epub_max_image_width

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

バージョン 1.2 で追加.

epub_show_urls

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

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

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

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

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

バージョン 1.2 で追加.

epub_use_index

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

バージョン 1.2 で追加.

epub_writing_mode

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

epub_writing_mode 'horizontal' 'vertical'
writing-mode [2] horizontal-tb vertical-rl
page progression left to right right to left
iBook’s Scroll Theme support scroll-axis is vertical. scroll-axis is horizontal.
[2]https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
epub3_page_progression_direction

ドキュメント全体の文字表記の方向です。この値は 'ltr' (left-to-right, 左から右)、'rtl' (right-to-left, 右から左)、 'default' のいずれかです。指定しない場合、'ltr' になります。

値に 'default' が指定された場合、著者は規定値を指定せず、表示時に方向を決定します。

バージョン 1.4 で追加.

バージョン 1.5 で撤廃: Use epub_writing_mode instead.

LaTeX出力のオプション

These options influence LaTeX output. See further LaTeX customization.

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 (default if language is 'ja')
latex_documents

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

  • startdocname: LaTeXファイルの”ルート”となるドキュメントの名前です。このファイルから参照されたすべてのドキュメントはLaTeXファイルの中のTOCツリーにも含まれるようになります。もしも1つのファイルをマスターにしたLaTeXファイルにしたい場合には、 master_doc で設定した値をここに指定して下さい。

  • targetname: 出力ディレクトリに出力される、LaTeXのファイル名です。

  • title: LaTeXのドキュメントのタイトルです。 startdoc の名前を使用する場合には、空にすることも可能です。この設定値はLaTeXのマークアップとして挿入されます。バックスラッシュやアンパサンドなどの特別な文字を入れる場合には、適切なLaTeXコマンドを使って表現しなければなりません。

  • 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).
  • documentclass: Normally, one of 'manual' or 'howto' (provided by Sphinx and based on 'report', resp. 'article'; Japanese documents use 'jsbook', resp. 'jreport'.) “howto” (non-Japanese) documents will not get appendices. Also they have a simpler title page. Other document classes can be given. Independently of the document class, the “sphinx” package is always loaded in order to define Sphinx’s custom LaTeX commands.
  • toctree_only: TrueFalse を設定します。もしも True を設定した場合には startdoc ドキュメント自身は出力には含まれず、そのドキュメントのTOCツリーで参照されたドキュメントだけになります。このオプションを付けると、HTMLではマスタードキュメント内の項目も表示させて、LaTeXでは出さない、ということができます。

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

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

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

latex_toplevel_sectioning

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

バージョン 1.4 で追加.

latex_use_parts

Trueが設定されると、一番上位のセクションの単位がpartになります。そうでない場合はchapterになります。デフォルトは False です。

バージョン 0.3 で追加.

バージョン 1.4 で撤廃: Use latex_toplevel_sectioning.

latex_appendices

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

latex_domain_indices

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

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

バージョン 1.0 で追加.

latex_use_modindex

Trueが設定されると、モジュールの索引がLaTeXのドキュメントに追加されます。デフォルトでは True です。

バージョン 1.0 で撤廃: latex_domain_indices を使用して下さい。

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_keep_old_macro_names

If True (default) the \strong, \code, \bfcode, \email, \tablecontinued, \titleref, \menuselection, \accelerator, \crossref, \termref, and \optional text styling macros are pre-defined by Sphinx and may be user-customized by some \renewcommand‘s inserted either via 'preamble' key or raw directive. If False, only \sphinxstrong, etc... macros are defined (and may be redefined by user). Setting to False may help solve macro name conflicts caused by user-added latex packages.

バージョン 1.4.5 で追加.

latex_elements

バージョン 0.5 で追加.

LaTeXのスニペットコードが含まれる辞書です。Sphinxはこれらのスニペットを使って、生成された .tex ファイルの中の要素をオーバーライドします。

Pythonの文字列中のバックスラッシュは、エスケープシーケンスとして解釈されるのを避けるために、2重に書く必要があります。

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

    'papersize'

    document classの用紙サイズのオプションです。 'a4paper''letterpaper' が指定できます。デフォルトは 'letterpaper' です。

    'pointsize'

    document classのポイントサイズのオプションです。 '10pt''11pt', '12pt' が指定できます。デフォルトは '10pt' です。

    'pxunit'

    the value of the px when used in image attributes width and height. The default value is '0.75bp' which achieves 96px=1in (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in use '0.01in' or '0.7227pt' (the latter leads to TeX computing a more precise value, due to the smaller unit used in the specification); for 72px=1in, simply use '1bp'; for 90px=1in, use '0.8bp' or '0.803pt'.

    バージョン 1.5 で追加.

    'sphinxsetup'

    A comma separated list of key=value package options for the Sphinx LaTeX style, default empty. See LaTeX customization.

    バージョン 1.5 で追加.

    'passoptionstopackages'

    A string which will be positioned early in the preamble, designed to contain \\PassOptionsToPackage{options}{foo} commands. Default empty.

    バージョン 1.4 で追加.

    'babel'

    “babel” package inclusion, default '\\usepackage{babel}' (the suitable document language string is passed as class option, and english is used if no language.) For Japanese documents, the default is the empty string.

    バージョン 1.5 で変更: For latex_engine set to 'xelatex', the default is '\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'.

    'fontpkg'

    フォントパッケージの挿入をします。デフォルトはTimesとHelveticaを使用する '\\usepackage{times}' です。 '' を指定すると、Computer Modernフォントが利用されます。

    バージョン 1.2 で変更: language がキリル文字を使用する場合、デフォルトを '' にしました。

    バージョン 1.5 で変更: Defaults to '' when latex_engine is 'xelatex'.

    'fncychap'

    Inclusion of the “fncychap” package (which makes fancy chapter titles), default '\\usepackage[Bjarne]{fncychap}' for English documentation (this option is slightly customized by Sphinx), '\\usepackage[Sonny]{fncychap}' for internationalized docs (because the “Bjarne” style uses numbers spelled out in English). Other “fncychap” styles you can try are “Lenny”, “Glenn”, “Conny”, “Rejne” and “Bjornstrup”. You can also set this to '' to disable fncychap.

    'preamble'

    Additional preamble content, default empty. See LaTeX customization.

    'atendofbody'

    Additional document content (right before the indices), default empty.

    バージョン 1.5 で追加.

    'figure_align'

    Latexの図のフロート配置で、デフォルトは ‘htbp’ (here, top, bottom, page) です。現在のページ内部にイメージがフィットしてようがしていまいが、次ページに ‘floated’ されますがおそらく他のどんなテキストよりも優先されます。もしあなたがこの動作を気に入らないのであれば、フローティングを無効化し図を厳密に配置しソース内に現れるよう ‘H’ を使ってください。

    バージョン 1.3 で追加.

    'footer'

    フッターのコンテンツ(索引の前)を追加します。デフォルトでは追加しません。

    バージョン 1.5 で撤廃: Use 'atendofbody' key instead.

  • Keys that don’t need to be overridden unless in special cases are:

    'maxlistdepth'

    LaTeX allows by default at most 6 levels for nesting list and quote-like environments, with at most 4 enumerated lists, and 4 bullet lists. Setting this key for example to '10' (as a string) will allow up to 10 nested levels (of all sorts). Leaving it to the empty string means to obey the LaTeX default.

    警告

    • Using this key may prove incompatible with some LaTeX packages or special document classes which do their own list customization.
    • The key setting is silently ignored if \usepackage{enumitem} is executed inside the document preamble. Use then rather the dedicated commands of this LaTeX package.

    バージョン 1.5 で追加.

    'inputenc'

    “inputenc” package inclusion, defaults to '\\usepackage[utf8]{inputenc}' when using pdflatex. Otherwise empty.

    バージョン 1.4.3 で変更: Previously '\\usepackage[utf8]{inputenc}' was used for all compilers.

    'cmappkg'

    “cmap” パッケージを挿入します。デフォルトでは '\\usepackage{cmap}' になります。

    バージョン 1.2 で追加.

    'fontenc'

    “fontenc”パッケージを挿入します。デフォルトでは '\\usepackage[T1]{fontenc}' になります。

    バージョン 1.5 で変更: Defaults to '\\usepackage{fontspec}' when latex_engine is 'xelatex'.

    'geometry'

    “geometry” package inclusion, the default definition is:

    '\\usepackage{geometry}'

    with an additional [dvipdfm] for Japanese documents. The Sphinx LaTeX style file executes:

    \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}

    which can be customized via corresponding ‘sphinxsetup’ options.

    バージョン 1.5 で追加.

    バージョン 1.5.2 で変更: dvipdfm option if latex_engine is 'platex'.

    バージョン 1.5.3 で追加: The ‘sphinxsetup’ keys for the margins.

    バージョン 1.5.3 で変更: The location in the LaTeX file has been moved to after \usepackage{sphinx} and \sphinxsetup{..}, hence also after insertion of 'fontpkg' key. This is in order to handle the paper layout options in a special way for Japanese documents: the text width will be set to an integer multiple of the zenkaku width, and the text height to an integer multiple of the baseline. See the hmargin documentation for more.

    'hyperref'

    “hyperref” package inclusion; also loads package “hypcap” and issues \urlstyle{same}. This is done after sphinx.sty file is loaded and before executing the contents of 'preamble' key.

    注意

    Loading of packages “hyperref” and “hypcap” is mandatory.

    バージョン 1.5 で追加: Previously this was done from inside sphinx.sty.

    'maketitle'

    “maketitle” call, default '\\maketitle' (but it has been redefined by the Sphinx manual and howto classes.) Override if you want to generate a differently-styled title page.

    'releasename'

    value that prefixes 'release' element on title page, default 'Release'. As for title and author used in the tuples of latex_documents, it is inserted as LaTeX markup.

    'tableofcontents'

    “tableofcontents” call, default '\\sphinxtableofcontents' (it is a wrapper of unmodified \tableofcontents, which may itself be customized by user loaded packages.) Override if you want to generate a different table of contents or put content between the title page and the TOC.

    バージョン 1.5 で変更: Previously the meaning of \tableofcontents itself was modified by Sphinx. This created an incompatibility with dedicated packages modifying it also such as “tocloft” or “etoc”.

    'transition'

    ページ切り替え表示に使うコマンドです。デフォルトでは '\n\n\\bigskip\\hrule{}\\bigskip\n\n' です。もし異なるページ切り替え表示を設定したい場合は上書きしてください。

    バージョン 1.2 で追加.

    'printindex'

    “printindex” call, the last thing in the file, default '\\printindex'. Override if you want to generate the index differently or append some content after the index. For example '\\footnotesize\\raggedright\\printindex' is advisable when the index is full of long entries.

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

    'docclass' 'classoptions' 'title' 'date' 'release' 'author' 'logo' 'makeindex' 'shorthandoff'

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 で変更: これは、Sphinxが提供するsphinx.styファイル等よりも優先されます。

latex_preamble

前書き(preamble)のLaTeXのマークアップを追加します。

バージョン 0.5 で撤廃: latex_elements'preamble' を使用して下さい。

latex_paper_size

出力する用紙サイズの('a4''letter')が指定できます。デフォルトは 'letter' です。

バージョン 0.5 で撤廃: latex_elements'papersize' を使用して下さい。

latex_font_size

フォントサイズです。 '10pt''11pt', '12pt' が指定できます。デフォルトは '10pt' です。

バージョン 0.5 で撤廃: latex_elements'pointsize' を使用して下さい。

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

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

text_newlines

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

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

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

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

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

バージョン 1.1 で追加.

text_sectionchars

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

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

バージョン 1.1 で追加.

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

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

man_pages

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

  • startdocname: manページの”ルート”となるドキュメントの名前です。このファイルから参照されたすべてのドキュメントはLaTeXファイルの中のTOCツリーにも含まれるようになります。もしも1つのファイルをマスターにしたmanページにしたい場合には、 master_doc で設定した値をここに指定して下さい。

  • name: manページの名前です。これには、スペースや特別な文字を含まない、短い文字列を指定します。この項目は出力ファイル名と、manページの名前(NAMEセクション内)として使用されます。

  • description: manページの説明です。これはNAMEセクション内で使用されます。

  • author: 著者名の文字列のリスト、もしくは単一の文字列です。manページのAUTHORSセクションを自動的に生成したくない場合には、空の文字列や空の配列も指定できます。

  • section: manページのセクションです。出力ファイル名や、manページのヘッダー内で使われます。

バージョン 1.0 で追加.

man_show_urls

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

バージョン 1.1 で追加.

Texinfo出力のオプション

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

texinfo_documents

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

  • startdocname: Texinfoファイルの”ルート”となるドキュメントの名前です。このファイルから参照されたすべてのドキュメントはTexinfoファイルの中のTOCツリーにも含まれるようになります。もしも1つのファイルをマスターにしたTexinfoファイルにしたい場合には、 master_doc で設定した値をここに指定して下さい。

  • targetname: 出力ディレクトリに出力される、Texinfoのファイル名(拡張子なし)です。

  • title: Texinfoのドキュメントのタイトルです。 startdoc の名前を使用する場合には、空にすることも可能です。Texinfoマークアップとして挿入されるため、 @ や {} などの特別な文字を入れるバアには、エスケープする必要があります。

  • author: Texinfoドキュメントの著者です。Texinfoマークアップとして挿入されます。複数人の名前を書く場合には、著者名の区切りに @* を使用して、 'John@*Sarah' のように書きます。

  • dir_entry: この名前は、トップレベルの DIR メニューファイルに表示されます。

  • description: トップレベルの DIR メニューファイルに表示される、説明用テキストです。

  • category: トップレベルの DIR メニューファイルに表示される、セクションを指定します。

  • toctree_only: TrueFalse を設定します。もしも True を設定した場合には startdoc ドキュメント自身は出力には含まれず、そのドキュメントのTOCツリーで参照されたドキュメントだけになります。このオプションを付けると、HTMLではマスタードキュメント内の項目も表示させて、Texinfoでは出さない、ということができます。

バージョン 1.1 で追加.

texinfo_appendices

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

バージョン 1.1 で追加.

texinfo_domain_indices

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

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

バージョン 1.1 で追加.

texinfo_show_urls

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

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

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

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

バージョン 1.1 で追加.

texinfo_no_detailmenu

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

バージョン 1.2 で追加.

texinfo_elements

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

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

    'paragraphindent'

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

    'exampleindent'

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

    'preamble'

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

    'copying'

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

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

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

バージョン 1.1 で追加.

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

linkcheck_ignore

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

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

バージョン 1.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 URIs that should skip checking the validity of anchors in links. This allows skipping entire sites, where anchors are used to control dynamic pages, or just specific anchors within a page, where javascript is used to add anchors dynamically, or use the fragment as part of to trigger an internal REST request. Default is ["/#!"].

バージョン 1.5 で追加.

XML出力のオプション

xml_pretty

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

バージョン 1.2 で追加.

脚注

[1](1, 2)

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

Options for the C++ domain

cpp_index_common_prefix

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

バージョン 1.5 で追加.

cpp_id_attributes

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

バージョン 1.5 で追加.

cpp_paren_attributes

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

バージョン 1.5 で追加.

Example of configuration file

# -*- coding: utf-8 -*-
#
# 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.
# This patterns also effect to 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

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#
# html_use_smartypants = True

# 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

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#
# latex_use_parts = False

# 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, will not define \strong, \code, \titleref, \crossref ... but only
# \sphinxstrong, ..., \sphinxtitleref, ... to help avoid clash with user added
# packages.
#
# latex_keep_old_macro_names = True

# 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']