Sphinx は標準の reST マークアップに対して、たくさんのディレクティブと “interpreted text roles” を拡張しています。このセクションにはそれらの拡張された構成部のリファレンスがあります。 “標準”の reST 構成部は、 Python ドキュメントで使用されてはいますが、そのドキュメントはここにはありません。
ノート
これは Sphinx の拡張マークアップの機能の概要です。網羅された情報は Sphinxのドキュメント <http://sphinx.pocoo.org/contents.html> にあります。
現在のセクションの著者を示します。引数には、(公表されないにしても)公表されても良いような名前と、email アドレスを含むべきです。アドレスのドメイン名部分は小文字で記述されるべきです。例:
.. sectionauthor:: Guido van Rossum <guido@python.org>
現在のところ、このマークアップは出力には全く利用されていませんが、だれが貢献したのかを把握するのに役に立っています。
この節では、ドキュメント中のモジュールに関する情報を提供するために使われるマークアップについて説明します。各モジュールは各々のファイルでドキュメントされるべきです。通常このマークアップは、そのファイルのタイトルヘッダの後に使います。典型的なファイルは次のように始まります:
:mod:`parrot` -- Dead parrot access
===================================
.. module:: parrot
:platform: Unix, Windows
:synopsis: Analyze and reanimate dead parrots.
.. moduleauthor:: Eric Cleese <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>
ごらんの通り、モジュール専用マークアップには、 module と moduleauthor という二つのディレクティブを持ちます。
このディレクティブはモジュールの説明の始まりを示します。(パッケージのサブモジュールの場合は、モジュール名はパッケージ名を含めて全体を記述すること)
platform オプションは、そのモジュールが利用可能なプラットフォームをカンマで区切ったリストです。(全てのプラットフォームで利用可能であるなら、このオプションは外すべきです)要素は短い識別子で、 “IRIX”, “Mac”, “Windows”, “Unix” などが使われています。できるだけ、すでに使われている識別子を使うようにしてください。
synopsis オプションは、モジュールの目的を説明する一文で構成されます。これは、現在のところ、 Global Module Index でのみ利用されています。
moduleauthor ディレクティブは、 sectionauthor と同じで、作者の名前になります。このディレクティブは、作者の人数だけ繰り返して利用できます。現在、このディレクティブは出力に利用されていません。
ノート
モジュールを解説するファイルのセクションタイトルは、概要ファイルの中の table-of-contents ツリーに利用されるので、意味が解るようにしてください。
モジュールが提供する機能を解説するために使うディレクティブが幾つかあります。各ディレクティブは、何を説明しようとしているのかを判別する情報として一つかそれ以上のシグネチャを必要とします。そして、ディレクティブの内容はその解説であるべきです。デフォルトではディレクティブはインデックスのエントリに登録されます。インデックスのエントリが必要ない場合は、ディレクティブオプションとして :noindex: というフラグを追加します。次の例は、ここまでで説明した要素を全て含んだディレクティブになります:
.. function:: spam(eggs)
ham(eggs)
:noindex:
Spam or ham the foo.
オブジェクトのメソッドやデータ属性(attribute)のシグネチャは、文脈からどの型に属しているかが明らかな場合であっても、 (.. method::FileInput.input(...)) のように型名を含める必要があります。これは、一貫したクロスリファレンスを実現するためです。 “context managers” といった抽象プロトコルに属するメソッドを解説する場合にも、インデックスを判りやすくするために、(仮想)型名を付けてください。
ディレクティブは以下の通りです。
Cの関数を説明します。シグネチャはC言語のまま付けてください。例:
.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
このディレクティブは関数ライクなプリプロセッサマクロを説明するのにも使います。引数の名前を省略しないでください。引数の名前を説明の中で利用できます。
シグネチャの中のアスタリスクをバックスラッシュでエスケープしなくても良いことを覚えておいてください。reST のインラインに対するパース処理は行われません。
Cの構造体メンバを説明します。シグネチャの例:
.. cmember:: PyObject* PyTypeObject.tp_bases
説明文は、値の取り得る範囲、値がどのように扱われるか、値を変更しても良いのかどうかについて記述するべきです。テキストの中で構造体のメンバを参照するときには member role を利用するべきです。
“シンプル”な C言語のマクロについて説明します。シンプルなマクロとは、引数を取らず、関数として解説されないものです。このディレクティブは単純な定数の定義には利用しません。 Python ドキュメントの中でこのディレクティブが使われている例には、 PyObject_HEAD と Py_BEGIN_ALLOW_THREADS があります。
C の型を説明します。シグネチャは単に型の名前であるべきです。
C のグローバル変数を説明します。シグネチャは、次の例のように、型を含めるべきです:
.. cvar:: PyObject* PyClass_Type
モジュール内のグローバルなデータを説明します。変数にも、 “定数として宣言された” 値にも利用します。クラスとオブジェクトの属性には使いません。
例外クラスについて説明します。シグネチャは、必要ではありませんが、コンストラクタ引数と丸括弧を含むことができます。
モジュールレベル関数を説明します。シグネチャには引数を記述するべきです。オプションの引数は角括弧で囲みます。明快さのために必要であれば、デフォルト値を含めることもできます。例:
.. function:: Timer.repeat([repeat=3[, number=1000000]])
このディレクティブはオブジェクトメソッドには利用されません。モジュールの名前空間にあり、モジュールの公開インタフェースになっている、束縛済みのオブジェクトメソッド (Bound object method) については、通常の関数とほとんど変わらないので、このディレクティブを使います。
説明文は、必要とされる引数と、それがどのように使われるか(特に、可変(mutable) オブジェクトが変更されるかどうか)、副作用、発生しうる例外についての情報を含むべきです。小さな例を提供するのも良いでしょう。
クラスを説明します。シグネチャには丸括弧とコンストラクタ引数を含めることができます。
オブジェクトの属性を説明します。説明文は、期待されるデータ型と、直接変更しても良いかどうかを含むべきです。
オブジェクトメソッドを説明します。パラメータからは、 self パラメータを除外するべきです。説明文は function と同じような情報を提供するべきです。
Python バイトコード(bytecode)の命令を説明します。
Python のコマンドラインオプションもしくはスイッチを説明します。オプションの引数名は <> の括弧で囲います。 例:
.. cmdoption:: -m <module>
module をスクリプトとして実行します。
Python が利用したり定義している環境変数を説明します。
もっと汎用的なバージョンの以下のディレクティブもあります:
このディレクティブは、上で説明したディレクティブと同じフォーマットを生成しますが、インデックスエントリやクロスリファレンスターゲットは生成しません。このディレクティブは、たとえば、このドキュメントでディレクティブの説明をするために利用しています。例:
.. describe:: opcode
Python バイトコードの命令を説明します。
Python ソースコードやインタラクティブセッションの例は、 reST 標準のリテラルブロックを利用して書きます。手前の段落の最後を :: にして、インデントで範囲を指定します。
インタラクティブセッションを表現するときは、プロンプトと出力を Python コードと一緒に書いてください。インタラクティブセッションに対して特別なマークアップは用意されていません。入力か出力の最後の行の後に、 “使用されない” プロンプトを入れてはいけません。次の例のように してはいけません
>>> 1 + 1
2
>>>
シンタックスハイライトはスマートに処理されます:
各ソースファイルには、 “ハイライト言語” があります。多数のファイルで Python のコードをハイライトするために、デフォルトでは 'python' に設定されています。
Python ハイライティングモードでは、インタラクティブセッションは自動的に認識されて適切にハイライトされます。
ハイライト言語は highlightlang ディレクティブを利用して変更することができます。以下のようにして利用します:
.. highlightlang:: c
このディレクティブで設定されたハイライト言語は、次の highlightlang ディレクティブまで有効になります。
ハイライト言語のよく使われる値は以下の通りです:
現在のハイライト言語でのハイライティングに失敗した場合、そのブロックは全くハイライトされません。
長い、そのまま表示されるテキストは、外部のプレインテキストのみで書かれたファイルに格納して、取り込む (include) こともできます。その場合、標準の include ディレクティブに literal オプションフラグを付けて利用します。たとえば、 example.py という Python ソースファイルを取り込む場合は:
.. include:: example.py
:literal:
前に述べたように、 Sphinx はドキュメント内に意味に基づくマークアップを挿入するために、 “interpreted text roles” を使います。
関数/メソッドの引数のようなローカル変数名は例外で、シンプルに *var* とマークされます。
その他の全ての role について、 :rolename:`content` のように書く必要があります。
そのほかにもクロスリファレンス role をより他用途にする便利な機能があります。
明示的なタイトルと参照ターゲットを、 reST の直接ハイパーリンクのように書くことができます: :role:`title <target>` は target を参照しますが、リンクテキストは title になります。
コンテントにprefix ! を付けると、参照もハイパーリンクも作られません。
Python オブジェクトのロールにおいて、コンテントに ~ というprefixをつけると、リンクターゲットはターゲットの最後の部分になります。例えば、 :meth:`~Queue.Queue.get` は Queue.Queue.get を参照しますが、リンクテキストとしては get だけを表示します。
HTML出力において、そのリンクの title 属性 (例えばマウスオーバー時のツールチップに表示される) は完全なターゲット名になります。
以下の roles はモジュール内のオブジェクトを参照し、該当する識別子があればハイパーリンクを作成します。
モジュールの名前。ドット付きの名前も使われる。これはパッケージの名前にも使う。
Python 関数の名前。ドット付きの名前も使われる。可読性のために、 role のテキストには後ろの丸括弧も含めるべきである。丸括弧は該当する識別子を検索するときには無視される。
モジュールレベル変数や定数の名前。
定数として “宣言された” 名前。これは C言語の #define か、 Python の変更されないことを意図された変数である。
クラス名。ドット付きの名前も使われる。
オブジェクトメソッドの名前。 role テキストには型の名前と、メソッド名、後続の丸括弧を含めるべきである。ドット付きの名前も使われる。
オブジェクトのデータ属性の名前。
例外の名前。ドット付きの名前も使われる。
このマークアップで囲まれた名前は、モジュール名とクラス名の両方あるいは片方を含めることができます。たとえば、 :func:`filter` は、現在のモジュール内にある filter という名前の関数か、その名前のビルトイン関数を参照できます。それに対して、 :func:`foo.filter` とすると、はっきりと foo モジュールの中の filter 関数だけを参照します。
同じようなことが、ある名前が現在ドキュメントしているクラスの属性かどうかを決定する際にも行われます。
以下の roles は、その C言語の要素が API ドキュメントにあれば、それに対するクロスリファレンスを作成します。
C言語の変数の名前。
C言語の関数の名前。後続の丸括弧も含めるべきである。
前述した、 “シンプルな” C のマクロの名前。
C言語の型の名前。
以下の role はクロスリファレンスは作るかもしれませんが、オブジェクトを参照する事はありません。
文法上のトークンの名前。(リファレンスマニュアルにおいて、出力間のリンクを作成するために使われます)
以下の roles はテキストのフォーマットスタイルを変更する以外何もしません。
rm のような、OS レベルのコマンドの名前。
テキストの中で定義される語をマークする。 (インデックスエントリは作成されない)
環境変数。インデックスエントリが作成される。
ファイルやディレクトリの名前。この中では、 “可変” な部分を示すために波括弧 “{}” を利用できる。例:
... は :file:`/usr/lib/python2.{x}/site-packages` にインストールされます ...
ビルドされたドキュメントの中では、この x は、 Python マイナーバージョンで置き換えられることを示すために、違った形式で表示されます。
インタラクティブなユーザーインタフェースの一部として表示されているラベルは、 guilabel を使ってマークされるべきです。これには、 curses やその他のテキストベースのライブラリを利用して作られた、テキストベースのインタフェースの中のラベルも含みます。ボタンラベル、ウィンドウタイトル、フィールド名、メニューとその項目、選択リスト内の要素など、インタフェース内のどんなラベルにも、この role を利用するべきです。
キーストロークシーケンスをマークアップします。キーシーケンスをどんな形式で表現するかは、プラットフォームやアプリケーションごとに慣習があります。適切な慣習が無い場合は、初心者や非ネイティブスピーカーにも判るように、修飾キー (modifier key) を省略形にしないでください。例えば、 xemacs キーシーケンスは、 :kbd:`C-x C-f` のように記述できますが、特定のアプリケーションやプラットフォームに関連づけられていない場合は、このキーシーケンスは :kbd:`Control-x Control-f` とマークアップされるべきです。
プログラミング言語の予約後(keyword).
RFC 822 形式のメールヘッダの名前。このマークアップは、そのヘッダが e-mail で利用されることを意味するわけではなく、同じ “スタイル” のどんなヘッダを参照するのにも使えます。多種の MIME 仕様で定義されているヘッダにも利用されます。ヘッダの名前は、実際に利用される場合と同じように書くべきで、一般的な使い方が複数ある場合は camel-case が好まれます。例: :mailheader:`Content-Type`.
make の変数名。
セクションを含む、Unix manual page への参照。例: :manpage:`ls(1)`.
メニュー項目は menuselection role を使ってマークアップされるべきです。これは、サブメニューや特定の操作のの選択を含め、完全なメニュー項目の並びや、その一部をマークアップするのに使われます。各項目の名前は --> を使って区切るべきです。
例えば、”スタート > プログラム” をマークアップする場合は、次の様にします:
:menuselection:`スタート --> プログラム`
幾つかのOSで、メニュー項目の後ろに何か記号を付けてダイアログボックスを開く事を示すといったことがあります。そういったメニュー項目の後ろに続く表記は、メニュー項目名に含めないべきです。
MIME type もしくは MIME type の構成要素 (メジャーもしくはマイナー部分だけ) の名前。
Usenet ニュースグループの名前。
実行可能プログラムのコマンドラインオプション。先頭のハイフンも含めなければならない。
実行可能プログラムの名前。幾つかのプラットフォームでは、実行可能ファイル名と異なるかもしれない。特に、Windows のプログラムでは、 .exe (もしくは他の) 拡張子は除くべきである。
正規表現。クォートを含めるべきではない。
コードのようなリテラルテキスト。 :file: と同じく、この中では “可変” な部分を示すために波括弧を利用できます。
“可変” 部分が要らないのであれば、通常の ``code`` を使ってください。
Python か C の、変数か引数の名前。
以下の roles は外部リンクを生成する:
Python Enhancement Proposal への参照。これは適切なインデックスのエントリを生成する。HTML出力では、 “PEP number” というテキストが生成され、このテキストは指定された PEP のオンラインコピーへのハイパーリンクになる。
Internet Request for Comments (RFC) への参照。これは適切なインデックスのエントリを生成する。HTML 出力では “RFC number” というテキストが生成され、このテキストは指定された RFC のオンラインコピーへのハイパーリンクになる。
ハイパーリンクのために特別な role が用意されていないことに注意してください。 reST 標準の方法がその目的に利用できるからです。
ドキュメント中の任意のセクションに対してのクロスリファレンスをサポートするには、 reST 標準のラベルはあまり良くありません。全てのラベルはセクションタイトルの前におかなければならず、全てのラベルの名前はドキュメントのソース全体に渡ってユニークでなければなりません。
そこで、セクションを参照するのには :ref:`label-name` という role を、利用できます。
例:
.. _my-reference-label:
クロスリファレンスされるセクション
----------------------------------
セクションの文字列。
このセクション自体を参照します。 :ref:`my-reference-label` を見てください。
.. _my-reference-label:
:ref: の部分はセクションタイトルで置き換えられます。
以下のディレクティブは、通常のテキストと同じように情報単位の中で利用でき、短いパラグラフを作成します。
この note に関係あるどの API を利用するときにも、ユーザーが気をつけるべき特に重要な情報。このディレクティブの内容は完全な文で、適切な句読点を全て含めなければなりません。
この warning に関係あるどの API を使うときにでも、ユーザーがとても慎重になるべき重要な情報。このディレクティブの内容は完全な文で、適切な句読点を全て含めなければなりません。警告だらけのページでユーザーを怖がらせないように、 node ではなく warning を使うのは、クラッシュ、データ損失、セキュリティに関する情報だけに留めるべきです。
このディレクティブは、どのバージョンの Python で対象の要素がライブラリや C API に追加されたのかを示します。このディレクティブがモジュール全体に適用する場合、ディレクティブをモジュールセクションのどの文章よりも先におかれるべきです。
最初の引数は必須で、バージョンです。二つ目の引数は任意で、変更点の 簡潔な 説明です。
例:
.. versionadded:: 2.5
*spam* 引数.
ディレクティブの先頭行と説明との間に空行を入れてはならないことに注意してください。これはマークアップされたときにブロックが視覚的に連続するためです。
versionadded とほとんど同じですが、対象の要素がいつどのように変更 (新しい引数が追加された、副作用が変わった、等) されたかを説明します。
このディレクティブは、 CPython に限定された情報を区別するために使います。ブロック要素としても、一文の引数としても利用できます。例えば
.. impl-detail::
This describes some implementation detail.
More explanation.
または、
.. impl-detail:: This shortly mentions an implementation detail.
内容の先頭に、自動的に “CPython implementation detail:” という一文が入ります。
たくさんのセクションで、モジュールドキュメントや外部ドキュメントが参照されています。これらのリストは、 seealso ディレクティブで作成されます。
seealso ディレクティブは一般的に、セクションの中で、どのサブセクションより前に置かれます。 HTML 出力では、本文の流れから切り離された区画の中に表示されます。
seealso ディレクティブの中身は、 reST の定義リストであるべきです。例:
.. seealso::
Module :mod:`zipfile`
:mod:`zipfile` 標準モジュールのドキュメント。
`GNU tar manual, Basic Tar Format <http://link>`_
GNU tar 拡張を含む、 tar アーカイブファイルのドキュメント。
このディレクティブは、目次 (table of contents) の項目にならない段落見出しを作ります。現在のところ、 “脚注” キャプションに利用されています。
このディレクティブは、センタリングされた太字の段落を作ります。次のようにして使います:
.. centered::
段落の内容
reST が複数のドキュメントを繋いだり、ドキュメントを複数のファイルに分割して出力する機能を持たないので、 Sphinx は table-of-contents を作成したり、ドキュメントの元ファイル間に関連を持たせたりするためにカスタムのディレクティブを利用しています。 toctree ディレクティブはその中心になる要素です。
このディレクティブは、ディレクティブの要素として与えられたファイルの中の TOCs (“sub-TOC trees” を含む) から作成した “TOC tree” をその場所に挿入します。 maxdepth オプションに数値を指定することで、 “TOC tree” の深さを指定できます。デフォルトでは全レベルを利用します。
Sphinx は自動的にインデックスのエントリを、先に述べた全ての情報の単位 (function, class, attribute のような) から作成します。
しかし、インデックスをより有用なものにしたり、言語リファレンスのような情報が情報の単位の中に含まれないようなドキュメントでもインデックスのエントリを作成できるようにするために、明示的なディレクティブも利用可能です。
そのディレクティブは index で、一つかそれ以上のインデックスエントリを含みます。各エントリは、種類と値をコロンで区切ったもので構成されます。
例:
.. index::
single: execution!context
module: __main__
module: sys
triple: module; search; path
このディレクティブは5つのエントリを持ち、 index 文の場所へのリンクになっているインデックスエントリに変換されます。(もしくは、オフラインメディアの場合、該当するページ番号になります)
利用可能なエントリの種類は:
形式的な文法の導出を表示するための特別なマークアップが利用可能です。このマークアップはシンプルで BNF (やその派生系) の全ての側面を表そうとはしていませんが、文脈自由文法 (context-free grammer) を、記号が使われている部分からその記号の定義部分へハイパーリンクが張られている形で表記するために十分な能力を提供しています。
このディレクティブは導出のグループを囲むために使われます。各導出は一つの行として渡され、名前と、コロンで区切られた残りの定義で構成されます。定義が複数行に渡る場合は、継続する各行は最初の行のコロンと同じ位置にあるコロンで始まらなければなりません。
空行は productionlist ディレクティブの引数として許可されていません。
定義には interpreted text としてマークアップされたトークン名を使うことができます。 (例: unaryneg ::= "-" `integer`) – これは、各トークンの導出に対するクロスリファレンスを作成します。代替を示すために利用される縦棒はバックスラッシュでエスケープしなければならないことに気をつけてください。そうしないと、 reST パーサーは縦棒を置換参照 (substitution reference) として認識するからです。
production においては、これ以上の reST パース処理が行われない事に注意してください。なので、 * や | といった文字をエスケープする必要がありません。
以下は Python リファレンスマニュアルの中の例です:
.. productionlist::
try_stmt: try1_stmt \| try2_stmt
try1_stmt: "try" ":" :token:`suite`
: ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+
: ["else" ":" :token:`suite`]
: ["finally" ":" :token:`suite`]
try2_stmt: "try" ":" :token:`suite`
: "finally" ":" :token:`suite`
ドキュメントシステムはデフォルトで定義されている3種類の置換を用意しています。それらはビルド設定ファイル conf.py で設定されます。
ドキュメントが言及している Python のリリースへ置換されます。これは、例えば 2.5.2b3 のような、 alpha/beta/release candiate を含む完全バージョン文字列です。
ドキュメントが言及している Python バージョンへ置換されます。これは、たとえばバージョン 2.5.1 において 2.5 の様に、バージョン文字列のうちメジャー・マイナー部のみで構成されます。
今日の日付か、ビルド設定ファイルで指定された日付のどちらかに置換されます。通常は April 14, 2007 のようなフォーマットになります。