.. highlightlang:: python .. The build configuration file .. ============================ ビルド設定ファイル ================== .. .. module:: conf :synopsis: Build configuration file. .. module:: conf :synopsis: ビルド設定ファイル .. The :term:`configuration directory` must contain a file named :file:`conf.py`. This file (containing Python code) is called the "build configuration file" and contains all configuration needed to customize Sphinx input and output behavior. :term:`コンフィグレーションディレクトリ` には必ず :file:`conf.py` が含まれています。このファイルは "ビルド設定ファイル" と呼ばれていて、Sphinxの入出力の動作をカスタマイズするのに必要な 設定はこのファイルに含まれています。この設定ファイルはPythonのプログラムとして書かれています。 .. The configuration file is executed as Python code at build time (using :func:`execfile`, and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file's namespace as its configuration. 設定ファイルは、ビルド時にPythonコードとして実行されます。 設定ファイルが含まれる フォルダをカレントディレクトリに設定し、:func:`execfile` を使用してコールされので、 任意の複雑なコードを記述することができます。Sphinxが読み込む際には単純にファイルの 中の名前空間に定義されている名前を使うことで、設定を読み込みます。 .. Important points to note: 詳細に説明するにあたっての注意点を列挙します。 .. * If not otherwise documented, values must be strings, and their default is the empty string. .. * The term "fully-qualified name" refers to a string that names an importable Python object inside a module; for example, the FQN ``"sphinx.builders.Builder"`` means the ``Builder`` class in the ``sphinx.builders`` module. .. * Remember that document names use ``/`` as the path separator and don't contain the file name extension. .. * Since :file:`conf.py` is read as a Python file, the usual rules apply for encodings and Unicode support: declare the encoding using an encoding cookie (a comment like ``# -*- coding: utf-8 -*-``) and use Unicode string literals when you include non-ASCII characters in configuration values. .. * The contents of the config namespace are pickled (so that Sphinx can find out when configuration changes), so it may not contain unpickleable values -- delete them from the namespace with ``del`` if appropriate. Modules are removed automatically, so you don't need to ``del`` your imports after use. .. * There is a special object named ``tags`` available in the config file. It can be used to query and change the tags (see :ref:`tags`). Use ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')`` to change. * 特別に指定されていない場合には、設定値は文字列型になります。また、指定されていない場合のデフォルト値は空文字列です。 * "完全限定名(FQN)"という用語は、モジュール内のインポート可能なPythonオブジェクトをあらわす名前です。例えば、 ``"sphinx.builders.Builder"`` という完全限定名は、 ``sphinx.builders`` モジュールにある ``Builder`` クラスを意味します。 * ドキュメント名は、パスのセパレータとして ``/`` を使用します。また、拡張子は含まないで表記します。 * :file:`conf.py` はPythonファイルとして読み込むため、Pythonの標準のエンコーディングや、ユニコードサポートなどを利用することができます。設定値にASCII文字以外の文字を含む場合には、エンコーディング宣言(行頭に ``# -*- coding: utf-8 -*-`` とコメントを入れる)を使用して、ユニコード文字列リテラルを使用してください。 * 設定の名前空間の内容はpickle化されます(そのため、Sphinxは設定の変更されたのを確認することができます)。そのため、pickle化できない値が含まれているのを発見したら、 ``del`` を使って名前空間から削除します。モジュールは自動的に削除されるため、 ``import`` したモジュールがあったら、使用後に ``del`` を行う必要はありません。 * 設定ファイルには、 ``tags`` という名前の特別なオブジェクトがあります。これはタグの問い合わせをしたり、変更したりするのに使用します。詳しくは :ref:`tags` も参照してください。問い合わせには ``tags.has('tag')`` 、変更には ``tags.add('tag')`` 、 ``tags.remove('tag')`` という使い方をします。 .. General configuration --------------------- 一般的な設定 ------------ .. confval:: extensions 使用したいSphinx拡張のモジュールを指定する配列です。この設定自体は配列で、中に、使用したい拡張モジュールの名前の文字列が含まれます。文字列としてはSphinxに付属のもの( ``sphinx.ext.*`` )か、カスタムの拡張機能を指定できます。 もし拡張機能が他のディレクトリにある場合には、confファイルの中で :data:`sys.path` にパスを追加することで、使用できるようになります。注意すべき点としては、絶対パスを指定しなければならない点です。もし、 :term:`コンフィグレーションディレクトリ` からの相対パスが分かっている場合には、以下のように :func:`os.path.abspath` を以下のように使用します:: import sys, os sys.path.append(os.path.abspath('sphinxext')) extensions = ['extname'] 上記のコードでは ``sphinxext`` というサブディレクトリに含まれる ``extname`` という名前の拡張機能をロードしています。 設定ファイル自身で拡張機能を実装してもかいません。その場合には、 :func:`setup` という名前の関数を提供する必要があります。 .. A list of strings that are module names of Sphinx extensions. These can be extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones. Note that you can extend :data:`sys.path` within the conf file if your extensions live in another directory -- but make sure you use absolute paths. If your extension path is relative to the :term:`configuration directory`, use :func:`os.path.abspath` like so:: import sys, os sys.path.append(os.path.abspath('sphinxext')) extensions = ['extname'] That way, you can load an extension called ``extname`` from the subdirectory ``sphinxext``. The configuration file itself can be an extension; for that, you only need to provide a :func:`setup` function in it. .. confval:: source_suffix ソースファイルに付く、ファイル名の拡張子を指定します。ここで指定された名前が末尾に付くファイルだけがソースファイルとして読み込まれます。デフォルトは ``'.rst'`` です。 .. The file name extension of source files. Only files with this suffix will be read as sources. Default is ``'.rst'``. .. confval:: source_encoding すべてのreSTのソースファイルのエンコーディングを指定します。デフォルトかつ、推奨のエンコーディングは ``'utf-8-sig'`` です。 .. versionadded:: 0.5 以前はSphinxはUTF-8エンコードされたソースしか読み込むことができませんでした。 .. The encoding of all reST source files. The recommended encoding, and the default value, is ``'utf-8-sig'``. .. versionadded:: 0.5 Previously, Sphinx accepted only UTF-8 encoded sources. .. confval:: master_doc "マスター"ドキュメントのドキュメント名を指定します。"マスター"ドキュメントには、ルートとなる :dir:`toctree` ディレクティブが含まれます。デフォルトは ``'contents'`` です。 .. The document name of the "master" document, that is, the document that contains the root :dir:`toctree` directive. Default is ``'contents'``. .. confval:: unused_docs ディレクトリ内には存在するが、現在はtoctreeに読み込まないドキュメント名のリストです。Sphinxはこのようなファイルがあると、警告を出力しますが、この警告を非表示にしたいときにこの設定を使用します。 .. A list of document names that are present, but not currently included in the toctree. Use this setting to suppress the warning that is normally emitted in that case. .. confval:: exclude_trees ソースファイルの検索から除外したいディレクトリパスの配列です。ソースディレクトリからの相対パスで、このフォルダからの再帰的な検索もされなくなるため、サブディレクトリも検索されません。デフォルトは ``[]`` です。 .. versionadded:: 0.4 .. A list of directory paths, relative to the source directory, that are to be recursively excluded from the search for source files, that is, their subdirectories won't be searched too. The default is ``[]``. .. versionadded:: 0.4 .. confval:: exclude_dirnames Sphinxが行う再帰的な処理で使用されたくないディレクトリ名のリストです。Sphinxではソースファイルの探索や静的ファイルのコピーなどで、再帰的にディレクトリを探索します。 ``'CVS'`` などの、バージョンコントロールのシステムのためのディレクトリを一括で除外したい場合などに便利です。デフォルトは ``[]`` です。 .. versionadded:: 0.5 .. A list of directory names that are to be excluded from any recursive operation Sphinx performs (e.g. searching for source files or copying static files). This is useful, for example, to exclude version-control-specific directories like ``'CVS'``. The default is ``[]``. .. versionadded:: 0.5 .. confval:: exclude_dirs ソースファイルの探索パスから除外したいパスが含まれるディレクトリ名のリストです。ソースディレクトリからの相対パスで指定します。 .. deprecated:: 0.5 この設定はサブディレクトリまでは考慮しないため、すべてのサブディレクトリを指定しなければなりません。 :confval:`exclude_trees` もしくは :confval:`exclude_dirnames` のどちらかのうち、使用したい用途にあったものを代わりに使用してください。 .. A list of directory names, relative to the source directory, that are to be excluded from the search for source files. .. deprecated:: 0.5 This does not take subdirs of the excluded directories into account. Use :confval:`exclude_trees` or :confval:`exclude_dirnames`, which match the expectations. .. confval:: locale_dirs .. versionadded:: 0.5 追加のSphinxメッセージカタログ( :confval:`language` 参照)を探索するディレクトリを指定します。ここで指定されたパスが、標準の :mod:`gettext` モジュールによって、 ``sphinx`` ドメインで検索されます。 :file:`./locale` を設定ファイルに指定した場合には、 :file:`./locale/{language}/LC_MESSAGES/sphinx.mo` という場所にメッセージカタログを置かなければなりません。 デフォルトは ``[]`` です。 .. Directories in which to search for additional Sphinx message catalogs (see :confval:`language`), relative to the source directory. The directories on this path are searched by the standard :mod:`gettext` module for a domain of ``sphinx``; so if you add the directory :file:`./locale` to this settting, the message catalogs must be in :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. The default is ``[]``. .. confval:: templates_path 追加のテンプレート(もしくは組み込みのテーマに関するテンプレートをオーバーライトするテンプレート)が含まれているパスのリストです。 コンフィギュレーションディレクトリからの相対パスで設定します。 .. A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory. .. confval:: template_bridge `~sphinx.application.TemplateBridge` のインスタンスを返す、呼び出し可能なオブジェクト、もしくはシンプルなクラスをあらわす完全限定名です。このインスタンスはHTMLドキュメントや、その他のビルダーの出力をレンダリングする際に使用されます。現在ではchanges builderに使用されています。テンプレートブリッジはHTMLテーマが使用された場合には、これに対応するように作られるべきです。 .. A string with the fully-qualified name of a callable (or simply a class) that returns an instance of :class:`~sphinx.application.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.) .. confval:: rst_epilog .. index:: pair: グローバル; 置換 読み込まれたすべてのソースファイルに挿入されるreSturucturedTextの文字列を設定します。この設定を利用すると、文字列置換をすべてのファイルに対して行いたいときに、うまく動作します:: rst_epilog = """ .. |psf| replace:: Pythonソフトウェア財団 """ .. versionadded:: 0.6 .. .. index:: pair: global; substitutions A string of reStructuredText that will be included at the end of every source file that is read. This is the right place to add substitutions that should be available in every file. An example:: rst_epilog = """ .. |psf| replace:: Python Software Foundation """ .. versionadded:: 0.6 .. confval:: default_role .. index:: デフォルト; ロール デフォルトロールとして使用する、reSTロールの名前(組み込み、もしくはSphinx拡張)を設定します。これは ```このような``` テキストのマークアップに対して適用されます。これは ``'obj'`` を ```filter``` として関数"filter" とのクロスリファレンスさせることができます(訳注:?)。デフォルトは ``None`` で、デフォルトのロールは適用されません。 デフォルトのロールは、reST標準の :dir:`default-role` ディレクティブを使用することによっても個々のドキュメントに対して設定することができます。 .. versionadded:: 0.4 .. .. index:: default; role The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up ```like this```. This can be set to ``'obj'`` to make ```filter``` a cross-reference to the function "filter". The default is ``None``, which doesn t reassign the default role. The default role can always be set within individual documents using the standard reST :dir:`default-role` directive. .. versionadded:: 0.4 .. confval:: keep_warnings Trueが設定されると、警告の内容がビルド済みドキュメントの"システムメッセージ"パラグラフの中に保存されます。この設定に関係なく、 ``sphinx-build`` 実行時標準エラー出力には警告が出力されます。 デフォルトは ``False`` で 0.5以前の振る舞いを維持するにはこのままにしてください。 .. versionadded:: 0.5 .. 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. The default is ``False``, the pre-0.5 behavior was to always keep them. .. versionadded:: 0.5 .. confval:: modindex_common_prefix モジュールのインデックスをソートする際に、無視するプリフィックスのリストです。例えば、 ``['foo.']`` が設定されると、 ``foo.bar`` に関しては ``foo.`` が削除されて ``bar`` になるため、 ``F`` ではなく、 ``B`` の項目として表示されます。プロジェクトの中のひとつのパッケージについてドキュメントを書く際にこの機能は便利に使えるでしょう。現在はHTMLビルダーについて使用されています。デフォルトは ``[]`` です。 .. versionadded:: 0.6 .. A list of prefixes that are ignored for sorting the module index (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, not ``F``). This can be handy if you document a project that consists of a single package. Works only for the HTML builder currently. Default is ``[]``. .. versionadded:: 0.6 .. confval:: trim_doctest_flags Trueのに設定されると、doctestを表す、Pythonのインタラクティブセッション形式のコードブロックの行末のdoctestのフラグ(``# doctest: FALG, ...`` ) が削除されます。デフォルトはTrueです。doctestに関連して可能なことはまだ多くありますので、詳しくはSphinx拡張モジュールの :mod:``~sphinx.ext.doctest` をご覧ください。 .. versionadded:: 1.0 .. If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at the ends of lines are removed for all code blocks showing interactive Python sessions (i.e. doctests). Default is true. See the extension :mod:`~sphinx.ext.doctest` for more possibilities of including doctests. .. Project information ------------------- プロジェクト情報 ---------------- .. confval:: project ドキュメントを書いているプロジェクト名です。 .. The documented project s name. .. confval:: copyright ``'2008, Author Name'`` という形式の著作権文です。 .. A copyright statement in the style ``'2008, Author Name'``. .. confval:: version 主要なプロジェクトのバージョンです。 ``|version|`` と置換されます。例えば、Pythonのドキュメントであれば、これは ``2.6`` になります。 .. The major project version, used as the replacement for ``|version|``. For example, for the Python documentation, this may be something like ``2.6``. .. confval:: release 完全なプロジェクトのバージョンです。HTMLのテンプレートなどの中の ``|release|`` と置換されます。例えば、Pthonのドキュメントの場合には、 ``2.6.0rc1`` のような文字列になります。 :confval:`version` と :confval:`release` を分けて設定する必要がなければ、同じ文字列を入れてください。 .. The full project version, used as the replacement for ``|release|`` and e.g. in the HTML templates. For example, for the Python documentation, this may be something like ``2.6.0rc1``. If you don t need the separation provided between :confval:`version` and :confval:`release`, just set them both to the same value. .. confval:: language ドキュメントの言語のコードです。Sphinxが自動的に生成する文章が、その言語で出力されるようになります。LaTeXビルダーでは *Babel* パッケージのオプションとして、適切な言語が選択されます。デフォルトは ``None`` で翻訳はされません(訳注:英語で出力されます) .. versionadded:: 0.5 現在は以下の言語をサポートしています: * ``cs`` -- チェコ語 * ``de`` -- ドイツ語 * ``en`` -- 英語 * ``es`` -- スペイン語 * ``fi`` -- フィンランド語 * ``fr`` -- フランス語 * ``it`` -- イタリア語 * ``nl`` -- オランダ語 * ``pl`` -- ポーランド語 * ``pt_BR`` -- ブラジルのポーランド語 * ``ru`` -- ロシア語 * ``sl`` -- スロベニア語 * ``uk_UA`` -- ウクライナ語 * ``zh_CN`` -- 簡体字中国語 * ``zh_TW`` -- 繁体字中国語 * ``ja`` -- 日本語 .. The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, in the LaTeX builder, a suitable language will be selected as an option for the *Babel* package. Default is ``None``, which means that no translation will be done. .. versionadded:: 0.5 Currently supported languages are: * ``cs`` -- Czech * ``de`` -- German * ``en`` -- English * ``es`` -- Spanish * ``fi`` -- Finnish * ``fr`` -- French * ``it`` -- Italian * ``nl`` -- Dutch * ``pl`` -- Polish * ``pt_BR`` -- Brazilian Portuguese * ``ru`` -- Russian * ``sl`` -- Slovenian * ``uk_UA`` -- Ukrainian * ``zh_CN`` -- Simplified Chinese * ``zh_TW`` -- Traditional Chinese .. confval:: today today_fmt これらの値は現在の日付をどのようにフォーマットするのか、というものを決めます。これは ``|today|`` を置き換える時に使用されます。 * もし :confval:`today` に空ではない値が設定されたらそれが使用されます。 * そうでない場合には、 :confval:`today_fmt` で与えられたフォーマットを使い、 :func:`time.strftime` で生成された値が使用されます。 デフォルトでは、 :confval:`today` は空で、 :confval:`today_fmt` には ``'%B %d, %Y'`` という値が設定されています。もしも :confval:`language` が設定されていて、翻訳機能が有効になっている場合には、選択された言語の %format が使用されます。 .. These values determine how to format the current date, used as the replacement for ``|today|``. * If you set :confval:`today` to a non-empty value, it is used. * Otherwise, the current time is formatted using :func:`time.strftime` and the format given in :confval:`today_fmt`. The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d, %Y'`` (or, if translation is enabled with :confval:`language`, am equivalent %format for the selected locale). .. confval:: highlight_language ドキュメント内でハイライトするデフォルトの言語を設定します。デフォルト値は ``'python'`` です。値はPygmentsのlexer名として有効な名前でなければなりません。詳しくは :ref:`code-examples` を参照してください。 .. versionadded:: 0.5 .. The default language to highlight source code in. The default is ``'python'``. The value should be a valid Pygments lexer name, see :ref:`code-examples` for more details. .. versionadded:: 0.5 .. confval:: pygments_style Pygmentsがソースコードをハイライトする際に使用するスタイルの名前を設定します。デフォルトは ``'sphinx'`` です。これはSphinxに合うようにデザインされた、デフォルトの組み込みのスタイルです。 .. versionchanged:: 0.3 もし値として、Pygmentsのカスタムスタイルクラスの完全限定名が指定されると、カスタムスタイルとして使用されます。 .. The style name to use for Pygments highlighting of source code. Default is ``'sphinx'``, which is a builtin style designed to match Sphinx default style. .. versionchanged:: 0.3 If the value is a fully-qualified name of a custom Pygments style class, this is then used as custom style. .. confval:: add_function_parentheses 関数とメソッドのロールテキストにカッコを付加するかどうかを決めるブール値です。ロールテキストというのは ``func:`input``` の ``input`` の箇所で、これをTrueにすると、その名前が呼び出し可能オブジェクトであるということが分かるようになります。デフォルトは ``True`` です。 .. A boolean that decides whether parentheses are appended to function and method role text (e.g. the content of ``:func:`input```) to signify that the name is callable. Default is ``True``. .. confval:: add_module_names :dir:`function` などの :term:`説明ユニット` のタイトルのすべてにモジュール名を付けるかどうかを決めるブール値です。デフォルトは ``True`` です。 .. A boolean that decides whether module names are prepended to all :term:`description unit` titles, e.g. for :dir:`function` directives. Default is ``True``. .. confval:: show_authors :dir:`moduleauthor` と :dir:`sectionauthor` ディレクティブの出力を、ビルドしたファイルに含めるかどうかのブール値です。 .. A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor` directives produce any output in the built files. .. confval:: trim_footnote_reference_space 脚注参照の前のスペースをトリムします。スペースはreSTパーサーが脚注を見分けるためには必要ですが、出力されると見た目があまり良くありません。 .. versionadded:: 0.6 .. Trim spaces before footnote references that are necessary for the reST parser to recognize the footnote, but do not look too nice in the output. .. versionadded:: 0.6 .. _html-options: HTML出力のオプション -------------------- .. Options for HTML output ----------------------- .. These options influence HTML as well as HTML Help output, and other builders that use Sphinx HTMLWriter class. これらのオプションはHTMLと、HTMLヘルプ出力、SphinxのHTMLWriterクラスを利用しているその他のビルダーに対して影響を与えます。 .. confval:: html_theme HTML出力で使用される"テーマ"です。詳しくは :doc:`テーマに関するセクション ` を参照してください。デフォルト値は ``'default'`` です。 .. versionadded:: 0.6 .. The "theme" that the HTML output should use. See the :doc:`section about theming `. The default is ``'default'``. .. versionadded:: 0.6 .. confval:: html_theme_options 選択したテーマのルックアンドフィールの設定を行うためのオプションのための辞書です。どのようなオプションがあるかは、テーマごとに異なります。組み込みのテーマで提供されるオプションに関しては、 :ref:`こちらのセクション ` を参照してください。 .. versionadded:: 0.6 .. A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. For the options understood by the builtin themes, see :ref:`this section `. .. versionadded:: 0.6 .. confval:: html_theme_path カスタムテーマを含むパスへのリストです。パスはテーマを含むサブディレクトリか、もしくはzipファイルを指定することができます。相対パスを設定すると、コンフィグレーションディレクトリからの相対パスになります。 .. versionadded:: 0.6 .. A list of paths that contain custom themes, either as subdirectories or as zip files. Relative paths are taken as relative to the configuration directory. .. versionadded:: 0.6 .. confval:: html_style HTMLページで使用されるスタイルシートを設定します。ここで指定されたファイル名はSphinxの :file:`static/` か、 :confval:`html_static_path` で与えられたパスのどちらかの中になければなりません。デフォルトでは選択されたテーマで提供されるスタイルシートを使用します。テーマで使用しているスタイルシートに対して、要素を追加したり、一部の要素の上書きしたいだけの場合には、テーマで提供されるスタイルシートを ``@import`` するようにしてください。 .. The style sheet to use for HTML pages. A file of that name must exist either in Sphinx :file:`static/` path, or in one of the custom paths given in :confval:`html_static_path`. Default is the stylesheet given by the selected theme. If you only want to add or override a few things compared to the theme s stylesheet, use CSS ``@import`` to import the theme s stylesheet. .. confval:: html_title Sphinx自身のテンプレートで生成されるHTMLドキュメントの"タイトル"を指定します。ここで設定された値は、それぞれのページ内の ```` タグに対して追加され、ナビゲーションバーの一番トップの要素として使用されます。デフォルト値は `'{<project>} v{<revision>} document'` となっています。内部のプレースホルダーは同名のコンフィグ値で置き換えられます。 .. The "title" for HTML documentation generated with Sphinx own templates. This is appended to the ``<title>`` tag of individual pages, and used in the navigation bar as the "topmost" element. It defaults to :samp:`'{<project>} v{<revision>} documentation'`, where the placeholders are replaced by the config values of the same name. .. confval:: html_short_title HTMLドキュメントの短いタイトルを設定します。これはヘッダ内のリンク、HTMLヘルプのドキュメントで使用されます。設定されない場合には、 :confval:`html_title` と同じ値がデフォルトで使用されます。 .. versionadded:: 0.4 .. A shorter "title" for the HTML docs. This is used in for links in the header and in the HTML Help docs. If not given, it defaults to the value of :confval:`html_title`. .. versionadded:: 0.4 .. confval:: html_logo もし設定されると、ドキュメントのロゴ画像として使用されます。設定値は家像ファイル名でなければなりません。画像ファイルはサイドバーのトップに表示されます。画像サイズの幅は200ピクセル以下にしてください。デフォルト値は ``None`` です。 .. versionadded:: 0.4.1 画像ファイルはHTML出力時に ``_static`` ディレクトリにコピーされます。もし同名のファイルが存在する場合には上書きされます。 .. If given, this must be the name of an image file that is the logo of the docs. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: ``None``. .. versionadded:: 0.4.1 The image file will be copied to the ``_static`` directory of the output HTML, so an already existing file with that name will be overwritten. .. confval:: html_favicon もし設定されると、ドキュメントのfaviconとして使用されます。設定値は静的なパスで、画像ファイルの名前でなければなりません。最近のブラウザでは、タブやウインドウ、ブックマークでこのfaviconの画像を利用します。これは 16x16 あるいは 32x32 の大きさの、Windowsの形式のアイコンファイル(``.ico``)でなければなりません。デフォルト値は ``None`` です。 .. versionadded:: 0.4 .. If given, this must be the name of an image file (within the static path, see below) that is the favicon of the docs. Modern browsers use this as icon for tabs, windows and bookmarks. It should be a Windows-style icon file (``.ico``), which is 16x16 or 32x32 pixels large. Default: ``None``. .. versionadded:: 0.4 .. confval:: html_static_path スタイルシートやスクリプトファイルといった、カスタムの静的ファイル類が含まれるパスのリストです。相対パスが設定されると、コンフィグレーションディレクトリからの相対パスとして処理されます。これらのファイルは、テーマが提供する静的ファイルをコピーした後にコピー処理が行われるため、 :file:`default.css` という名前のファイルがあると、テーマで使用する :file:`default.css` を上書きしてしまうので注意してください。 .. versionchanged:: 0.4 :confval:`html_static_path` で指定されるパスにはサブディレクトリも含めることができます。 .. A list of paths that contain custom static files (such as style sheets or script files). Relative paths are taken as relative to the configuration directory. They are copied to the output directory after the theme s static files, so a file named :file:`default.css` will overwrite the theme s :file:`default.css`. .. versionchanged:: 0.4 The paths in :confval:`html_static_path` can now contain subdirectories. .. confval:: html_last_updated_fmt 空の文字列以外が設定されると、すべてのページの最下部に挿入される '最終更新:' というタイムスタンプを出力されるためのテンプレートとして使用されます。テンプレートは :func:`strftime` で解釈できるフォーマットを指定してください。デフォルトは ``'%b %d, %Y'`` (ロケールによって異なります)になります。 .. If this is not the empty string, a 'Last updated on:' timestamp is inserted at every page bottom, using the given :func:`strftime` format. Default is ``'%b %d, %Y'`` (or a locale-dependent equivalent). .. confval:: html_use_smartypants Trueが設定されると、 *SmartyPants* は、印刷上で実体を修正するために引用文とダッシュを変換するのに使用されるでしょう。 デフォルトは ``True`` です。 .. If true, *SmartyPants* will be used to convert quotes and dashes to typographically correct entities. Default: ``True``. .. confval:: html_add_permalinks Trueが設定されると、 Sphinxはそれぞれの見出しに "パーマリンク" を追加します。 .. versionadded:: 0.6 以前は常に有効になってました。 .. If true, Sphinx will add "permalinks" for each heading and description environment as paragraph signs that become visible when the mouse hovers over them. Default: ``True``. .. versionadded:: 0.6 Previously, this was always activated. .. confval:: html_sidebars カスタムのサイドバーのテンプレートです。設定値は、ドキュメント名をキーに、テンプレート名を値に持つ辞書として設定します:: html_sidebars = { 'using/windows': 'windowssidebar.html' } この設定では、与えられたドキュメントのサイドバーに, ``windowssidebar.html`` テンプレートをレンダリングします。 .. Custom sidebar templates, must be a dictionary that maps document names to template names. Example:: html_sidebars = { 'using/windows': 'windowssidebar.html' } .. This will render the template ``windowssidebar.html`` within the sidebar of the given document. .. confval:: html_additional_pages HTMLページにレンダリングする、追加のHTMLテンプレートを指定します。設定値はドキュメント名をキーに、テンプレート名を値に持つ辞書として設定します:: html_additional_pages = { 'download': 'customdownload.html', } この設定では、 ``customdownload.html`` というテンプレートが ``download.html`` というページにレンダリングされます。 .. note:: Sphinxの昔のバージョンには :confval:`html_index` と呼ばれる値を持っていて、これだけが唯一 "index" ドキュメントのコンテンツを制御する方法でした。もしこの機能を使っていた場合には、 ``html_additional_pages`` に ``index`` というキーを追加して、それまで使用していたカスタムテンプレートを値として設定します。その後、カスタムテンプレートを下記のように書き換えます:: {% extend "defindex.html" %} {% block tables %} ... 古いテンプレートの内容 ... {% endblock %} .. Additional templates that should be rendered to HTML pages, must be a dictionary that maps document names to template names. Example:: html_additional_pages = { 'download': 'customdownload.html', } This will render the template ``customdownload.html`` as the page ``download.html``. .. note:: Earlier versions of Sphinx had a value called :confval:`html_index` which was a clumsy way of controlling the content of the "index" document. If you used this feature, migrate it by adding an ``'index'`` key to this setting, with your custom template as the value, and in your custom template, use :: {% extend "defindex.html" %} {% block tables %} ... old template content ... {% endblock %} .. confval:: html_use_modindex もしTrueに設定されると、HTMLドキュメントにモジュールの索引を挿入します。デフォルトは ``True`` です。 .. If true, add a module index to the HTML documents. Default is ``True``. .. confval:: html_use_index Trueが設定されると、HTMLドキュメントに索引を追加します。デフォルトは ``True`` です。 .. versionadded:: 0.4 .. If true, add an index to the HTML documents. Default is ``True``. .. versionadded:: 0.4 .. confval:: html_split_index もしTrueが設定されると、索引が2回作成されます。一つ目は全てのエントリーを含む索引です。2つめは最初の文字ごとにページ分割された索引になります。デフォルトは ``False`` です。 .. versionadded:: 0.4 .. If true, the index is generated twice: once as a single page with all the entries, and once as one page per starting letter. Default is ``False``. .. versionadded:: 0.4 .. confval:: html_copy_source Trueに設定されると、 HTMLのビルド時に :file:`_sources/{name}` としてreSTのソースファイルが含まれるようになります。デフォルトは ``True`` です。 .. warning:: もしもこの設定値が ``False`` に設定されると、 JavaScriptの検索機能を使用したときに、マッチしたドキュメントのタイトルしか表示できなくなります。マッチした文章の内容を表示することはできません。 .. If true, the reST sources are included in the HTML build as :file:`_sources/{name}`. The default is ``True``. .. warning:: If this config value is set to ``False``, the JavaScript search function will only display the titles of matching documents, and no excerpt from the matching contents. .. confval:: html_show_sourcelink :confval:`html_copy_source` がTrueに設定されていて、かつ、この設定値もTrueに設定された場合に、サイドバーにreSTのソースファイルへのリンクを表示します。デフォルト値は ``True`` です。 .. versionadded:: 0.6 .. If true (and :confval:`html_copy_source` is true as well), links to the reST sources will be added to the sidebar. The default is ``True``. .. versionadded:: 0.6 .. confval:: html_use_opensearch もしこの値が空でなかったら、 `OpenSearch <http://opensearch.org>` の説明ファイルが生成され、すべてのページにこのファイルを参照する ``<link>`` タグが含まれるようになります。OpenSearchが検索ページの位置を示すのに、相対パスをサポートしていないので、 この値はこの設定値の値は、これらのドキュメントが提供されるベースのURLにします。最後のスラッシュ(/)は不要です。例えば、Pythonのドキュメントであれば、 ``"http://docs.python.org"`` とします。デフォルト値は ``''`` です。 .. If nonempty, an `OpenSearch <http://opensearch.org>` description file will be output, and all pages will contain a ``<link>`` tag referring to it. Since OpenSearch doesnt support relative URLs for its search page location, the value of this option must be the base URL from which these documents are served (without trailing slash), e.g. ``"http://docs.python.org"``. The default is ``''``. .. confval:: html_file_suffix .. versionadded:: 0.4 もし空でなければ、HTMLファイルを生成するときに、ファイル名の末尾に追加される文字列として使用されます。デフォルトでは ``".html"`` となります。 .. If nonempty, this is the file name suffix for generated HTML files. The default is ``".html"``. .. versionadded:: 0.4 .. confval:: html_link_suffix HTMLファイルに対して生成されるリンクの末尾に付けられる文字列です。デフォルト値としては :confval:`html_file_suffix` の値が設定されます。他のウェブサーバのセットアップをサポートする場合などに、別の値を設定することができます。 .. versionadded:: 0.6 .. Suffix for generated links to HTML files. The default is whatever :confval:`html_file_suffix` is set to; it can be set differently (e.g. to support different web server setups). .. versionadded:: 0.6 .. confval:: html_translator_class HTML変換クラスへの完全限定名(FQN)を表す文字列です。これはSphinxの :class:`~sphinx.writers.html.HTMLTranslator` のサブクラスです。これはドキュメントツリーをHTMLに変換するのに使用されます。デフォルト値は ``None`` で、組み込みのトランスレータが使用されます。 .. A string with the fully-qualified name of a HTML Translator class, that is, a subclass of Sphinx :class:`~sphinx.writers.html.HTMLTranslator`, that is used to translate document trees to HTML. Default is ``None`` (use the builtin translator). .. confval:: html_show_copyright もしTrueに設定されると、 "(C) Copyright ..." という文字列をHTMLのフッターに出力します。デフォルトは ``True`` です。 .. versionadded:: 1.0 .. If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``. .. confval:: html_show_sphinx もしTrueが設定されると、 "このドキュメントは Sphinx 0.6.2 で生成しました。" という説明がHTMLのフッターに追加されます。デフォルトは ``True`` です。 .. versionadded:: 0.4 .. If true, "Created using Sphinx" is shown in the HTML footer. Default is ``True``. .. versionadded:: 0.4 .. confval:: html_output_encoding HTML出力ファイルのエンコーディングを指定します。デフォルトは ``'utf-8'`` です。このエンコーディング名Pythonのエンコーディング指定と、HTMLの ``charset`` の両方で使用できる名前でなければなりません。 .. versionadded:: 1.0 .. Encoding of HTML output files. Default is ``'utf-8'``. Note that this encoding name must both be a valid Python encoding name and a valid HTML ``charset`` value. .. confval:: htmlhelp_basename HTMLヘルプビルダーについて、出力ファイルのベース名を設定します。デフォルト値は ``'pydoc'`` です。 .. Output file base name for HTML help builder. Default is ``'pydoc'``. .. _latex-options: Options for LaTeX output ------------------------ These options influence LaTeX output. .. confval:: 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, documentclass, toctree_only)``, where the items are: * *startdocname*: document name that is the "root" of the LaTeX file. All documents referenced by it in TOC trees will be included in the LaTeX file too. (If you want only one LaTeX file, use your :confval:`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*. 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'``. * *documentclass*: Must be one of ``'manual'`` or ``'howto'``. Only "manual" documents will get appendices. Also, howtos will have a simpler title page. * *toctree_only*: Must be ``True`` or ``False``. If ``True``, the *startdoc* document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output. .. versionadded:: 0.3 The 6th item ``toctree_only``. Tuples with 5 items are still accepted. .. confval:: latex_logo If given, this must be the name of an image file (relative to the configuration directory) that is the logo of the docs. It is placed at the top of the title page. Default: ``None``. .. confval:: latex_use_parts If true, the topmost sectioning unit is parts, else it is chapters. Default: ``False``. .. versionadded:: 0.3 .. confval:: latex_appendices A list of document names to append as an appendix to all manuals. .. confval:: latex_use_modindex If true, add a module index to LaTeX documents. Default is ``True``. .. confval:: latex_elements .. versionadded:: 0.5 A dictionary that contains LaTeX snippets that override those Sphinx usually puts into the generated ``.tex`` files. Keep in mind that backslashes must be doubled in Python string literals to avoid interpretation as escape sequences. * Keys that you may want to override include: ``'papersize'`` Paper size option of the document class (``'a4paper'`` or ``'letterpaper'``), default ``'letterpaper'``. ``'pointsize'`` Point size option of the document class (``'10pt'``, ``'11pt'`` or ``'12pt'``), default ``'10pt'``. ``'babel'`` "babel" package inclusion, default ``'\\usepackage{babel}'``. ``'fontpkg'`` Font package inclusion, default ``'\\usepackage{times}'`` (which uses Times and Helvetica). You can set this to ``''`` to use the Computer Modern fonts. ``'fncychap'`` Inclusion of the "fncychap" package (which makes fancy chapter titles), default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation, ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because the "Bjarne" style uses numbers spelled out in English). Other "fncychap" styles you can try include "Lenny", "Glenn", "Conny" and "Rejne". You can also set this to ``''`` to disable fncychap. ``'preamble'`` Additional preamble content, default empty. ``'footer'``` Additional footer content (before the indices), default empty. * Keys that don't need be overridden unless in special cases are: ``'inputenc'`` "inputenc" package inclusion, default ``'\\usepackage[utf8]{inputenc}'``. ``'fontenc'`` "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``. ``'maketitle'`` "maketitle" call, default ``'\\maketitle'``. Override if you want to generate a differently-styled title page. ``'tableofcontents'`` "tableofcontents" call, default ``'\\tableofcontents'``. Override if you want to generate a different table of contents or put content between the title page and the TOC. ``'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. * Keys that are set by other options and therefore should not be overridden are: ``'docclass'`` ``'classoptions'`` ``'title'`` ``'date'`` ``'release'`` ``'author'`` ``'logo'`` ``'releasename'`` ``'makeindex'`` ``'makemodindex'`` ``'shorthandoff'`` ``'printmodindex'`` .. confval:: latex_docclass A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document classes that will be used as the base for the two Sphinx classes. Default is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``. .. versionadded:: 1.0 .. confval:: latex_additional_files A list of file names, relative to the configuration directory, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn't copy automatically, e.g. if they are referenced in custom LaTeX added in ``latex_elements``. Image files that are referenced in source files (e.g. via ``.. image::``) are copied automatically. You have to make sure yourself that the filenames don't collide with those of any automatically copied files. .. versionadded:: 0.6 .. confval:: latex_preamble Additional LaTeX markup for the preamble. .. deprecated:: 0.5 Use the ``'preamble'`` key in the :confval:`latex_elements` value. .. confval:: latex_paper_size The output paper size (``'letter'`` or ``'a4'``). Default is ``'letter'``. .. deprecated:: 0.5 Use the ``'papersize'`` key in the :confval:`latex_elements` value. .. confval:: latex_font_size The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``. .. deprecated:: 0.5 Use the ``'pointsize'`` key in the :confval:`latex_elements` value.