コンフィグレーションディレクトリ には必ず conf.py が含まれています。このファイルは “ビルド設定ファイル” と呼ばれていて、Sphinxの入出力の動作をカスタマイズするのに必要な 設定はこのファイルに含まれています。この設定ファイルはPythonのプログラムとして書かれています。
設定ファイルは、ビルド時にPythonコードとして実行されます。 設定ファイルが含まれる フォルダをカレントディレクトリに設定し、:func:execfile を使用してコールされので、 任意の複雑なコードを記述することができます。Sphinxが読み込む際には単純にファイルの 中の名前空間に定義されている名前を使うことで、設定を読み込みます。
詳細に説明するにあたっての注意点を列挙します。
使用したい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() という名前の関数を提供する必要があります。
すべてのreSTのソースファイルのエンコーディングを指定します。デフォルトかつ、推奨のエンコーディングは 'utf-8-sig' です。
バージョン 0.5 で追加: 以前はSphinxはUTF-8エンコードされたソースしか読み込むことができませんでした。
ソースファイルの検索から除外したいディレクトリパスの配列です。ソースディレクトリからの相対パスで、このフォルダからの再帰的な検索もされなくなるため、サブディレクトリも検索されません。デフォルトは [] です。
バージョン 0.4 で追加.
Sphinxが行う再帰的な処理で使用されたくないディレクトリ名のリストです。Sphinxではソースファイルの探索や静的ファイルのコピーなどで、再帰的にディレクトリを探索します。 'CVS' などの、バージョンコントロールのシステムのためのディレクトリを一括で除外したい場合などに便利です。デフォルトは [] です。
バージョン 0.5 で追加.
ソースファイルの探索パスから除外したいパスが含まれるディレクトリ名のリストです。ソースディレクトリからの相対パスで指定します。
バージョン 0.5 で撤廃: この設定はサブディレクトリまでは考慮しないため、すべてのサブディレクトリを指定しなければなりません。 exclude_trees もしくは exclude_dirnames のどちらかのうち、使用したい用途にあったものを代わりに使用してください。
バージョン 0.5 で追加.
追加のSphinxメッセージカタログ( language 参照)を探索するディレクトリを指定します。ここで指定されたパスが、標準の gettext モジュールによって、 sphinx ドメインで検索されます。 ./locale を設定ファイルに指定した場合には、 ./locale/language/LC_MESSAGES/sphinx.mo という場所にメッセージカタログを置かなければなりません。
デフォルトは [] です。
読み込まれたすべてのソースファイルに挿入されるreSturucturedTextの文字列を設定します。この設定を利用すると、文字列置換をすべてのファイルに対して行いたいときに、うまく動作します:
rst_epilog = """
.. |psf| replace:: Pythonソフトウェア財団
"""
バージョン 0.6 で追加.
デフォルトロールとして使用する、reSTロールの名前(組み込み、もしくはSphinx拡張)を設定します。これは `このような` テキストのマークアップに対して適用されます。これは 'obj' を `filter` として関数”filter” とのクロスリファレンスさせることができます(訳注：?)。デフォルトは None で、デフォルトのロールは適用されません。
デフォルトのロールは、reST標準の default-role ディレクティブを使用することによっても個々のドキュメントに対して設定することができます。
バージョン 0.4 で追加.
Trueが設定されると、警告の内容がビルド済みドキュメントの”システムメッセージ”パラグラフの中に保存されます。この設定に関係なく、 sphinx-build 実行時標準エラー出力には警告が出力されます。
デフォルトは False で 0.5以前の振る舞いを維持するにはこのままにしてください。
バージョン 0.5 で追加.
モジュールのインデックスをソートする際に、無視するプリフィックスのリストです。例えば、 ['foo.'] が設定されると、 foo.bar に関しては foo. が削除されて bar になるため、 F ではなく、 B の項目として表示されます。プロジェクトの中のひとつのパッケージについてドキュメントを書く際にこの機能は便利に使えるでしょう。現在はHTMLビルダーについて使用されています。デフォルトは [] です。
バージョン 0.6 で追加.
完全なプロジェクトのバージョンです。HTMLのテンプレートなどの中の |release| と置換されます。例えば、Pthonのドキュメントの場合には、 2.6.0rc1 のような文字列になります。
ドキュメントの言語のコードです。Sphinxが自動的に生成する文章が、その言語で出力されるようになります。LaTeXビルダーでは Babel パッケージのオプションとして、適切な言語が選択されます。デフォルトは None で翻訳はされません(訳注:英語で出力されます)
バージョン 0.5 で追加.
現在は以下の言語をサポートしています:
これらの値は現在の日付をどのようにフォーマットするのか、というものを決めます。これは |today| を置き換える時に使用されます。
デフォルトでは、 today は空で、 today_fmt には '%B %d, %Y' という値が設定されています。もしも language が設定されていて、翻訳機能が有効になっている場合には、選択された言語の %format が使用されます。
ドキュメント内でハイライトするデフォルトの言語を設定します。デフォルト値は 'python' です。値はPygmentsのlexer名として有効な名前でなければなりません。詳しくは code-examples を参照してください。
バージョン 0.5 で追加.
Pygmentsがソースコードをハイライトする際に使用するスタイルの名前を設定します。デフォルトは 'sphinx' です。これはSphinxに合うようにデザインされた、デフォルトの組み込みのスタイルです。
バージョン 0.3 で変更: もし値として、Pygmentsのカスタムスタイルクラスの完全限定名が指定されると、カスタムスタイルとして使用されます。
脚注参照の前のスペースをトリムします。スペースはreSTパーサーが脚注を見分けるためには必要ですが、出力されると見た目があまり良くありません。
バージョン 0.6 で追加.
これらのオプションはHTMLと、HTMLヘルプ出力、SphinxのHTMLWriterクラスを利用しているその他のビルダーに対して影響を与えます。
HTML出力で使用される”テーマ”です。詳しくは テーマに関するセクション を参照してください。デフォルト値は 'default' です。
バージョン 0.6 で追加.
選択したテーマのルックアンドフィールの設定を行うためのオプションのための辞書です。どのようなオプションがあるかは、テーマごとに異なります。組み込みのテーマで提供されるオプションに関しては、 こちらのセクション を参照してください。
バージョン 0.6 で追加.
カスタムテーマを含むパスへのリストです。パスはテーマを含むサブディレクトリか、もしくはzipファイルを指定することができます。相対パスを設定すると、コンフィグレーションディレクトリからの相対パスになります。
バージョン 0.6 で追加.
HTMLドキュメントの短いタイトルを設定します。これはヘッダ内のリンク、HTMLヘルプのドキュメントで使用されます。設定されない場合には、 html_title と同じ値がデフォルトで使用されます。
バージョン 0.4 で追加.
もし設定されると、ドキュメントのロゴ画像として使用されます。設定値は家像ファイル名でなければなりません。画像ファイルはサイドバーのトップに表示されます。画像サイズの幅は200ピクセル以下にしてください。デフォルト値は None です。
バージョン 0.4.1 で追加: 画像ファイルはHTML出力時に _static ディレクトリにコピーされます。もし同名のファイルが存在する場合には上書きされます。
もし設定されると、ドキュメントのfaviconとして使用されます。設定値は静的なパスで、画像ファイルの名前でなければなりません。最近のブラウザでは、タブやウインドウ、ブックマークでこのfaviconの画像を利用します。これは 16x16 あるいは 32x32 の大きさの、Windowsの形式のアイコンファイル(.ico)でなければなりません。デフォルト値は None です。
バージョン 0.4 で追加.
スタイルシートやスクリプトファイルといった、カスタムの静的ファイル類が含まれるパスのリストです。相対パスが設定されると、コンフィグレーションディレクトリからの相対パスとして処理されます。これらのファイルは、テーマが提供する静的ファイルをコピーした後にコピー処理が行われるため、 default.css という名前のファイルがあると、テーマで使用する default.css を上書きしてしまうので注意してください。
バージョン 0.4 で変更: html_static_path で指定されるパスにはサブディレクトリも含めることができます。
Trueが設定されると、 Sphinxはそれぞれの見出しに “パーマリンク” を追加します。
バージョン 0.6 で追加: 以前は常に有効になってました。
カスタムのサイドバーのテンプレートです。設定値は、ドキュメント名をキーに、テンプレート名を値に持つ辞書として設定します:
html_sidebars = {
'using/windows': 'windowssidebar.html'
}
この設定では、与えられたドキュメントのサイドバーに, windowssidebar.html テンプレートをレンダリングします。
HTMLページにレンダリングする、追加のHTMLテンプレートを指定します。設定値はドキュメント名をキーに、テンプレート名を値に持つ辞書として設定します:
html_additional_pages = {
'download': 'customdownload.html',
}
この設定では、 customdownload.html というテンプレートが download.html というページにレンダリングされます。
ノート
Sphinxの昔のバージョンには html_index と呼ばれる値を持っていて、これだけが唯一 “index” ドキュメントのコンテンツを制御する方法でした。もしこの機能を使っていた場合には、 html_additional_pages に index というキーを追加して、それまで使用していたカスタムテンプレートを値として設定します。その後、カスタムテンプレートを下記のように書き換えます:
{% extend "defindex.html" %}
{% block tables %}
... 古いテンプレートの内容 ...
{% endblock %}
Trueが設定されると、HTMLドキュメントに索引を追加します。デフォルトは True です。
バージョン 0.4 で追加.
もしTrueが設定されると、索引が２回作成されます。一つ目は全てのエントリーを含む索引です。2つめは最初の文字ごとにページ分割された索引になります。デフォルトは False です。
バージョン 0.4 で追加.
Trueに設定されると、 HTMLのビルド時に _sources/name としてreSTのソースファイルが含まれるようになります。デフォルトは True です。
警告
もしもこの設定値が False に設定されると、 JavaScriptの検索機能を使用したときに、マッチしたドキュメントのタイトルしか表示できなくなります。マッチした文章の内容を表示することはできません。
html_copy_source がTrueに設定されていて、かつ、この設定値もTrueに設定された場合に、サイドバーにreSTのソースファイルへのリンクを表示します。デフォルト値は True です。
バージョン 0.6 で追加.
バージョン 0.4 で追加.
もし空でなければ、HTMLファイルを生成するときに、ファイル名の末尾に追加される文字列として使用されます。デフォルトでは ".html" となります。
HTMLファイルに対して生成されるリンクの末尾に付けられる文字列です。デフォルト値としては html_file_suffix の値が設定されます。他のウェブサーバのセットアップをサポートする場合などに、別の値を設定することができます。
バージョン 0.6 で追加.
もしTrueに設定されると、 “(C) Copyright ...” という文字列をHTMLのフッターに出力します。デフォルトは True です。
バージョン 1.0 で追加.
もしTrueが設定されると、 “このドキュメントは Sphinx 0.6.2 で生成しました。” という説明がHTMLのフッターに追加されます。デフォルトは True です。
バージョン 0.4 で追加.
HTML出力ファイルのエンコーディングを指定します。デフォルトは 'utf-8' です。このエンコーディング名Pythonのエンコーディング指定と、HTMLの charset の両方で使用できる名前でなければなりません。
バージョン 1.0 で追加.
These options influence LaTeX output.
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:
バージョン 0.3 で追加: The 6th item toctree_only. Tuples with 5 items are still accepted.
If true, the topmost sectioning unit is parts, else it is chapters. Default: False.
バージョン 0.3 で追加.
バージョン 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:
Paper size option of the document class ('a4paper' or 'letterpaper'), default 'letterpaper'.
Point size option of the document class ('10pt', '11pt' or '12pt'), default '10pt'.
“babel” package inclusion, default '\\usepackage{babel}'.
Font package inclusion, default '\\usepackage{times}' (which uses Times and Helvetica). You can set this to '' to use the Computer Modern fonts.
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.
Additional preamble content, default empty.
Additional footer content (before the indices), default empty.
Keys that don’t need be overridden unless in special cases are:
“inputenc” package inclusion, default '\\usepackage[utf8]{inputenc}'.
“fontenc” package inclusion, default '\\usepackage[T1]{fontenc}'.
“maketitle” call, default '\\maketitle'. Override if you want to generate a differently-styled title page.
“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” 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'
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'.
バージョン 1.0 で追加.
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.
バージョン 0.6 で追加.
Additional LaTeX markup for the preamble.
バージョン 0.5 で撤廃: Use the 'preamble' key in the latex_elements value.
The output paper size ('letter' or 'a4'). Default is 'letter'.
バージョン 0.5 で撤廃: Use the 'papersize' key in the latex_elements value.
The font size (‘10pt’, ‘11pt’ or ‘12pt’). Default is '10pt'.
バージョン 0.5 で撤廃: Use the 'pointsize' key in the latex_elements value.