目次

前のトピックへ

3. reStructuredText の基礎

次のトピックへ

5. LaTeX マークアップとの違い

このページ

4. 拡張マークアップ構成部 (Additional Markup Constructs)

Sphinx は標準の reST マークアップに対して、たくさんのディレクティブと “interpreted text roles” を拡張しています。 このセクションにはそれらの拡張された構成部のリファレンスがあります。 “標準”の reST 構成部は、 Python ドキュメントで使用されてはいますが、 そのドキュメントはここにはありません。

ノート

これは Sphinx の拡張マークアップの機能の概要です。 網羅された情報は Sphinxのドキュメント <http://sphinx.pocoo.org/contents.html> にあります。

4.1. メタ情報マークアップ (Meta-information markup)

sectionauthor

現在のセクションの著者を示します。引数には、(公表されないにしても)公表されても 良いような名前と、email アドレスを含むべきです。 アドレスのドメイン名部分は小文字で記述されるべきです。例:

.. sectionauthor:: Guido van Rossum <guido@python.org>

現在のところ、このマークアップは出力には全く利用されていませんが、だれが貢献した のかを把握するのに役に立っています。

4.2. モジュール用のマークアップ (Module-specific markup)

この節では、ドキュメント中のモジュールに関する情報を提供するために使われるマークアップに ついて説明します。各モジュールは各々のファイルでドキュメントされるべきです。 通常このマークアップは、そのファイルのタイトルヘッダの後に使います。典型的な ファイルは次のように始まります:

: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>

ごらんの通り、モジュール専用マークアップには、 modulemoduleauthor という二つのディレクティブを持ちます。

module

このディレクティブはモジュールの説明の始まりを示します。 (パッケージのサブモジュールの場合は、モジュール名はパッケージ名を含めて全体を 記述すること)

platform オプションは、そのモジュールが利用可能なプラットフォームをカンマで 区切ったリストです。(全てのプラットフォームで利用可能であるなら、このオプションは 外すべきです)要素は短い識別子で、 “IRIX”, “Mac”, “Windows”, “Unix” などが使われ ています。できるだけ、すでに使われている識別子を使うようにしてください。

synopsis オプションは、モジュールの目的を説明する一文で構成されます。 これは、現在のところ、 Global Module Index でのみ利用されています。

moduleauthor

moduleauthor ディレクティブは、``sectionauthor`` と同じで、作者の名前になります。 このディレクティブは、作者の人数だけ繰り返して利用できます。 現在、このディレクティブは出力に利用されていません。

ノート

モジュールを解説するファイルのセクションタイトルは、概要ファイルの中の table-of-contents ツリーに利用されるので、意味が解るようにしてください。

4.3. 情報単位 (Information units)

モジュールが提供する機能を解説するために使うディレクティブが幾つかあります。 各ディレクティブは、何を説明しようとしているのかを判別する情報として 一つかそれ以上のシグネチャを必要とします。そして、ディレクティブの内容は その解説であるべきです。 デフォルトではディレクティブはインデックスのエントリに登録されます。 インデックスのエントリが必要ない場合は、ディレクティブオプションとして :noindex: というフラグを追加します。 次の例は、ここまでで説明した要素を全て含んだディレクティブになります:

.. function:: spam(eggs)
              ham(eggs)
   :noindex:

   Spam or ham the foo.

オブジェクトのメソッドやデータ属性(attribute)のシグネチャは、文脈からどの型に 属しているかが明らかな場合であっても、 (.. method::FileInput.input(...)) の ように型名を含める必要があります。これは、一貫したクロスリファレンスを実現する ためです。 “context managers” といった抽象プロトコルに属するメソッドを解説する場合にも、 インデックスを判りやすくするために、(仮想)型名を付けてください。

ディレクティブは以下の通りです。

cfunction

Cの関数を説明します。シグネチャはC言語のまま付けてください。例:

.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

このディレクティブは関数ライクなプリプロセッサマクロを説明するのにも使います。 引数の名前を省略しないでください。引数の名前を説明の中で利用できます。

シグネチャの中のアスタリスクをバックスラッシュでエスケープしなくても良いことを 覚えておいてください。reST のインラインに対するパース処理は行われません。

cmember

Cの構造体メンバを説明します。シグネチャの例:

.. cmember:: PyObject* PyTypeObject.tp_bases

説明文は、値の取り得る範囲、値がどのように扱われるか、値を変更しても良いのかどうかに ついて記述するべきです。テキストの中で構造体のメンバを参照するときには member role を 利用するべきです。

cmacro

“シンプル”な C言語のマクロについて説明します。シンプルなマクロとは、引数を取らず、 関数として解説されないものです。このディレクティブは単純な定数の定義には利用しません。 Python ドキュメントの中でこのディレクティブが使われている例には、 PyObject_HEADPy_BEGIN_ALLOW_THREADS があります。

ctype

C の型を説明します。シグネチャは単に型の名前であるべきです。

cvar

C のグローバル変数を説明します。シグネチャは、次の例のように、型を含めるべき です:

.. cvar:: PyObject* PyClass_Type
data

モジュール内のグローバルなデータを説明します。変数にも、 “定数として宣言された” 値にも利用します。クラスとオブジェクトの属性には使いません。

exception

例外クラスについて説明します。シグネチャは、必要ではありませんが、コンストラクタ 引数と丸括弧を含むことができます。

function

モジュールレベル関数を説明します。シグネチャには引数を記述するべきです。 オプションの引数は角括弧で囲みます。明快さのために必要であれば、デフォルト値を 含めることもできます。例:

.. function:: Timer.repeat([repeat=3[, number=1000000]])

このディレクティブはオブジェクトメソッドには利用されません。モジュールの名前空間にあり、 モジュールの公開インタフェースになっている、束縛済みのオブジェクトメソッド (Bound object method) については、通常の関数とほとんど変わらないので、 このディレクティブを使います。

説明文は、必要とされる引数と、それがどのように使われるか(特に、可変(mutable) オブジェクトが 変更されるかどうか)、副作用、発生しうる例外についての情報を含むべきです。 小さな例を提供するのも良いでしょう。

class

クラスを説明します。シグネチャには丸括弧とコンストラクタ引数を含めることが できます。

attribute

オブジェクトの属性を説明します。説明文は、期待されるデータ型と、直接変更しても 良いかどうかを含むべきです。

method

オブジェクトメソッドを説明します。パラメータからは、 self パラメータを除外 するべきです。説明文は function と同じような情報を提供するべきです。

opcode

Python バイトコードの命令を説明します。

もっと汎用的なバージョンの以下のディレクティブもあります:

describe

このディレクティブは、上で説明したディレクティブと同じフォーマットを生成しますが、 インデックスエントリやクロスリファレンスターゲットは生成しません。 このディレクティブは、たとえば、このドキュメントでディレクティブの説明をする ために利用しています。例:

.. describe:: opcode

   Python バイトコードの命令を説明します。

4.4. コードサンプルを表示する (Showing code examples)

Python ソースコードやインタラクティブセッションの例は、 reST 標準のリテラルブロックを 利用して書きます。手前の段落の最後を :: にして、インデントで範囲を指定します。

インタラクティブセッションを表現するときは、プロンプトと出力を Python コードと一緒に 書いてください。インタラクティブセッションに対して特別なマークアップは用意されて いません。入力か出力の最後の行の後に、 “使用されない” プロンプトを入れてはいけません。 次の例のように してはいけません

>>> 1 + 1
2
>>>

シンタックスハイライトはスマートに処理されます:

  • 各ソースファイルには、 “ハイライト言語” があります。多数のファイルで Python の コードをハイライトするために、デフォルトでは 'python' に設定されています。

  • Python ハイライティングモードでは、インタラクティブセッションは自動的に認識 されて適切にハイライトされます。

  • ハイライト言語は highlightlang ディレクティブを利用して変更することができます。 以下のようにして利用します:

    .. highlightlang:: c
    

    このディレクティブで設定されたハイライト言語は、次の highlightlang ディレクティブ まで有効になります。

  • ハイライト言語のよく使われる値は以下の通りです:

    • python (デフォルト)
    • c
    • rest
    • none (ハイライトなし)
  • 現在のハイライト言語でのハイライティングに失敗した場合、そのブロックは全く ハイライトされません。

長い、そのまま表示されるテキストは、外部のプレインテキストのみで書かれたファイルに 格納して、取り込む (include) こともできます。その場合、標準の include ディレクティブに literal オプションフラグを付けて利用します。たとえば、 example.py という Python ソースファイルを取り込む場合は:

.. include:: example.py
   :literal:

4.5. インラインマークアップ (Inline markup)

前に述べたように、 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 はモジュール内のオブジェクトを参照し、該当する識別子があればハイパーリンクを 作成します。

mod

モジュールの名前。ドット付きの名前も使われる。これはパッケージの名前にも使う。

func

Python 関数の名前。ドット付きの名前も使われる。可読性のために、 role のテキストには 後ろの丸括弧も含めるべきである。丸括弧は該当する識別子を検索するときには無視される。

data

モジュールレベル変数や定数の名前。

const

定数として “宣言された” 名前。これは C言語の #define か、 Python の変更されないことを意図された変数である。

class

クラス名。ドット付きの名前も使われる。

meth

オブジェクトメソッドの名前。 role テキストには型の名前と、メソッド名、後続の 丸括弧を含めるべきである。ドット付きの名前も使われる。

attr

オブジェクトのデータ属性の名前。

exc

例外の名前。ドット付きの名前も使われる。

このマークアップで囲まれた名前は、モジュール名とクラス名の両方あるいは片方を 含めることができます。たとえば、 :func:`filter` は、現在のモジュール内にある filter という名前の関数か、その名前のビルトイン関数を参照できます。 それに対して、 :func:`foo.filter` とすると、はっきりと foo モジュールの 中の filter 関数だけを参照します。

同じようなことが、ある名前が現在ドキュメントしているクラスの属性かどうかを 決定する際にも行われます。

以下の roles は、その C言語の要素が API ドキュメントにあれば、それに対する クロスリファレンスを作成します。

cdata

C言語の変数の名前。

cfunc

C言語の関数の名前。後続の丸括弧も含めるべきである。

cmacro

前述した、 “シンプルな” C のマクロの名前。

ctype

C言語の型の名前。

以下の role はクロスリファレンスは作るかもしれませんが、オブジェクトを参照する 事はありません。

token

文法上のトークンの名前。(リファレンスマニュアルにおいて、出力間のリンクを 作成するために使われます)


以下の roles はテキストのフォーマットスタイルを変更する以外何もしません。

command

rm のような、OS レベルのコマンドの名前。

dfn

テキストの中で定義される語をマークする。 (インデックスエントリは 作成されない)

envvar

環境変数。インデックスエントリが作成される。

file

ファイルやディレクトリの名前。この中では、 “可変” な部分を示すために 波括弧 “{}” を利用できる。例:

... は :file:`/usr/lib/python2.{x}/site-packages` にインストールされます ...

ビルドされたドキュメントの中では、この x は、 Python マイナーバージョンで 置き換えられることを示すために、違った形式で表示されます。

guilabel

インタラクティブなユーザーインタフェースの一部として表示されているラベルは、 guilabel を使ってマークされるべきです。これには、 curses やその他の テキストベースのライブラリを利用して作られた、テキストベースのインタフェースの 中のラベルも含みます。ボタンラベル、ウィンドウタイトル、フィールド名、メニューと その項目、選択リスト内の要素など、インタフェース内のどんなラベルにも、この role を 利用するべきです。

kbd

キーストロークシーケンスをマークアップします。キーシーケンスをどんな形式で表現 するかは、プラットフォームやアプリケーションごとに慣習があります。適切な慣習が 無い場合は、初心者や非ネイティブスピーカーにも判るように、修飾キー (modifier key) を省略形にしないでください。例えば、 xemacs キーシーケンスは、 :kbd:`C-x C-f` のように記述できますが、特定のアプリケーションやプラットフォームに関連づけられて いない場合は、このキーシーケンスは :kbd:`Control-x Control-f` とマークアップ されるべきです。

keyword

プログラミング言語の予約後(keyword).

mailheader

RFC 822 形式のメールヘッダの名前。このマークアップは、そのヘッダが e-mail で 利用されることを意味するわけではなく、同じ “スタイル” のどんなヘッダを参照する のにも使えます。多種の MIME 仕様で定義されているヘッダにも利用されます。ヘッダの 名前は、実際に利用される場合と同じように書くべきで、一般的な使い方が複数ある 場合は camel-case が好まれます。例: :mailheader:`Content-Type`.

makevar

make の変数名。

manpage

セクションを含む、Unix manual page への参照。例: :manpage:`ls(1)`.

menuselection

メニュー項目は menuselection role を使ってマークアップされるべきです。 これは、サブメニューや特定の操作のの選択を含め、完全なメニュー項目の並びや、 その一部をマークアップするのに使われます。各項目の名前は --> を使って 区切るべきです。

例えば、”スタート > プログラム” をマークアップする場合は、次の様にします:

:menuselection:`スタート --> プログラム`

幾つかのOSで、メニュー項目の後ろに何か記号を付けてダイアログボックスを開く 事を示すといったことがあります。そういったメニュー項目の後ろに続く表記は、 メニュー項目名に含めないべきです。

mimetype

MIME type もしくは MIME type の構成要素 (メジャーもしくはマイナー部分だけ) の名前。

newsgroup

Usenet ニュースグループの名前。

option

実行可能プログラムのコマンドラインオプション。先頭のハイフンも含めなければ ならない。

program

実行可能プログラムの名前。幾つかのプラットフォームでは、実行可能ファイル名と 異なるかもしれない。特に、Windows のプログラムでは、 .exe (もしくは他の) 拡張子は除くべきである。

regexp

正規表現。クォートを含めるべきではない。

samp

コードのようなリテラルテキスト。 :file: と同じく、この中では “可変” な部分を示すために波括弧を 利用できます。

“可変” 部分が要らないのであれば、通常の ``code`` を使ってください。

var

Python か C の、変数か引数の名前。

以下の roles は外部リンクを生成する:

pep

Python Enhancement Proposal への参照。これは適切なインデックスのエントリを 生成する。HTML出力では、 “PEP number” というテキストが生成され、この テキストは指定された PEP のオンラインコピーへのハイパーリンクになる。

rfc

Internet Request for Comments (RFC) への参照。これは適切なインデックスのエントリを 生成する。HTML 出力では “RFC number” というテキストが生成され、この テキストは指定された RFC のオンラインコピーへのハイパーリンクになる。

ハイパーリンクのために特別な role が用意されていないことに注意してください。 reST 標準の方法がその目的に利用できるからです。

4.6. クロスリンクのマークアップ (Cross-linking markup)

ドキュメント中の任意のセクションに対してのクロスリファレンスをサポートするには、 reST 標準のラベルはあまり良くありません。全てのラベルはセクションタイトルの前に おかなければならず、全てのラベルの名前はドキュメントのソース全体に渡って ユニークでなければなりません。

そこで、セクションを参照するのには :ref:`label-name` という role を、利用 できます。

例:

.. _my-reference-label:

クロスリファレンスされるセクション
----------------------------------

セクションの文字列。

このセクション自体を参照します。 :ref:`my-reference-label` を見てください。

.. _my-reference-label:

:ref: の部分はセクションタイトルで置き換えられます。

4.7. 段落レベルでのマークアップ (Paragraph-level markup)

以下のディレクティブは、通常のテキストと同じように情報単位の中で利用でき、 短いパラグラフを作成します。

note

この note に関係あるどの API を利用するときにも、ユーザーが気をつけるべき 特に重要な情報。このディレクティブの内容は完全な文で、適切な句読点を全て含め なければなりません。

warning

この warning に関係あるどの API を使うときにでも、ユーザーがとても慎重になるべき 重要な情報。このディレクティブの内容は完全な文で、適切な句読点を全て含め なければなりません。 note との違いは、セキュリティに関する情報について、 note よりも推奨されていることです。

versionadded

このディレクティブは、どのバージョンの Python で対象の要素がライブラリや C API に追加されたのかを示します。このディレクティブがモジュール全体に適用する場合、 ディレクティブをモジュールセクションのどの文章よりも先におかれるべきです。

最初の引数は必須で、バージョンです。二つ目の引数は任意で、変更点の 簡潔な 説明です。

例:

.. versionadded:: 2.5
   *spam* 引数.

ディレクティブの先頭行と説明との間に空行を入れてはならないことに注意してください。 これはマークアップされたときにブロックが視覚的に連続するためです。

versionchanged

versionadded とほとんど同じですが、対象の要素がいつどのように変更 (新しい引数が 追加された、副作用が変わった、等) されたかを説明します。


seealso

たくさんのセクションで、モジュールドキュメントや外部ドキュメントが参照されています。 これらのリストは、 seealso ディレクティブで作成されます。

seealso ディレクティブは一般的に、セクションの中で、どのサブセクションより 前に置かれます。 HTML 出力では、本文の流れから切り離された区画の中に表示されます。

seealso ディレクティブの中身は、 reST の定義リストであるべきです。例:

.. seealso::

   Module :mod:`zipfile`
      :mod:`zipfile` 標準モジュールのドキュメント。

   `GNU tar manual, Basic Tar Format <http://link>`_
      GNU tar 拡張を含む、 tar アーカイブファイルのドキュメント。
rubric

このディレクティブは、目次 (table of contents) の項目にならない段落見出しを 作ります。現在のところ、 “脚注” キャプションに利用されています。

centered

このディレクティブは、センタリングされた太字の段落を作ります。次のようにして 使います:

.. centered::

   段落の内容

4.8. Table-of-contents マークアップ (Table-of-contents markup)

reST が複数のドキュメントを繋いだり、ドキュメントを複数のファイルに分割して出力する 機能を持たないので、 Sphinx は table-of-contents を作成したり、ドキュメントの元ファイル 間に関連を持たせたりするためにカスタムのディレクティブを利用しています。 toctree ディレクティブはその中心になる要素です。

toctree

このディレクティブは、ディレクティブの要素として与えられたファイルの中の TOCs (“sub-TOC trees” を含む) から作成した “TOC tree” をその場所に挿入します。 maxdepth オプションに数値を指定することで、 “TOC tree” の深さを指定できます。 デフォルトでは全レベルを利用します。

4.9. インデックス生成マークアップ (Index-generating markup)

Sphinx は自動的にインデックスのエントリを、先に述べた全ての情報の単位 (function, class, attribute のような) から作成します。

しかし、インデックスをより有用なものにしたり、言語リファレンスのような情報が 情報の単位の中に含まれないようなドキュメントでもインデックスのエントリを作成 できるようにするために、明示的なディレクティブも利用可能です。

そのディレクティブは index で、一つかそれ以上のインデックスエントリを含みます。 各エントリは、種類と値をコロンで区切ったもので構成されます。

例:

.. index::
   single: execution!context
   module: __main__
   module: sys
   triple: module; search; path

このディレクティブは5つのエントリを持ち、 index 文の場所へのリンクになっている インデックスエントリに変換されます。(もしくは、オフラインメディアの場合、該当する ページ番号になります)

利用可能なエントリの種類は:

single
単独のインデックスエントリを生成します。サブエントリのテキストをセミコロンで 区切る(これは以降の種類でも、どんなエントリを作るのかを指定するときに使います) ことによってサブエントリを作成できます。
pair
pair: loop; statement は、 loop; statementstatement; loop という 名前の二つのインデックスエントリを一度に作成するショートカットです。
triple
同じように、 triple: module; search; path; は、 module; search path, search; path, module, path; module search というエントリを作成する ショートカットです。
module, keyword, operator, object, exception, statement, builtin
これらは全て二つのインデックスエントリを作成します。例えば、 module: hashlib は、 module; hashlibhashlib; module を作ります。

4.10. 文法導出表記 (Grammar production displays)

形式的な文法の導出を表示するための特別なマークアップが利用可能です。 このマークアップはシンプルで BNF (やその派生系) の全ての側面を表そうとはしていま せんが、文脈自由文法 (context-free grammer) を、記号が使われている部分からその 記号の定義部分へハイパーリンクが張られている形で表記するために十分な能力を 提供しています。

productionlist

このディレクティブは導出のグループを囲むために使われます。各導出は一つの行として 渡され、名前と、コロンで区切られた残りの定義で構成されます。定義が複数行に 渡る場合は、継続する各行は最初の行のコロンと同じ位置にあるコロンで始まらなければ なりません。

空行は 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`

4.11. 置換 (Substitutions)

ドキュメントシステムはデフォルトで定義されている3種類の置換を用意しています。 それらはビルド設定ファイル conf.py で設定されます。

|release|

ドキュメントが言及している Python のリリースへ置換されます。これは、例えば 2.5.2b3 のような、 alpha/beta/release candiate を含む完全バージョン文字列です。

|version|

ドキュメントが言及している Python バージョンへ置換されます。これは、たとえば バージョン 2.5.1 において 2.5 の様に、バージョン文字列のうちメジャー・ マイナー部のみで構成されます。

|today|

今日の日付か、ビルド設定ファイルで指定された日付のどちらかに置換されます。 通常は April 14, 2007 のようなフォーマットになります。