モジュール用のマークアップ

このセクションで説明するマークアップはドキュメントの書かれているモジュールに対して情報を提供するものです。

それでは、モジュールのドキュメンテーションに利用できるディレクティブの説明をします:

.. module:: 名前

このディレクティブはモジュールの説明の開始時に使用します。パッケージやサブモジュールにも使用できますが、この場合はパッケージ名を含む、完全な名前を指定してください。この ディレクティブは class ディレクティブのようなコンテンツを作成することはできません。

このディレクティブを使用すると、グローバルモジュールインデックスに項目が追加されます。

platform オプションが存在していれば、そのモジュールが利用可能なモジュールをカンマ区切りで指定します。もしすべてのプラットフォームで利用可能であれば、このオプションは使用しないようにしましょう。プラットフォーム名としては、短い識別子、例えば、”IRIX”, “Mac”, “Windows”, “Unix”などから利用してください。もし適用時点ですでに使用されているキーがあれば、それを使用してください。

synopsis オプションには、モジュールの目的を説明する文章を書くことができます。現在のバージョンでは、これはグローバルモジュールインデックスの中でのみ使用されます。

deprecated オプションを使用すると、このモジュールが古くて、使用するのを推奨しない、ということを示すことができます。オプションは取りません。このディレクティブは様々な場所で使用されるでしょう。

.. currentmodule:: 名前

このディレクティブはSphinxに対して、この行以降のクラスや関数などが、指定された与えられたモジュール ( module のように)の中にある、ということを通知します。これを使用しても、インデックスのエントリーは作成されません。 mod へのリンクターゲットも作成されません。このディレクティブは、モジュールに含まれる項目へのドキュメントが様々なファイルやセクションに分割されている場合に便利です。この場合には一カ所だけ module ディレクティブを使用して、他の箇所で currentmodule を使用するようにします。

.. moduleauthor:: 名前 <Eメール>

moduleauthor ディレクティブは何度も書くことができます。 sectionauthor でドキュメントの一部に対して著者の名前を何人も指定できるように、モジュールコードの著者の名前を指定できます。これも show_authors 設定値をTrueにすると出力されます。

ノート

これは概要ファイルの目次のツリーに挿入されるようになります。モジュール説明ファイルのセクションタイトルの情報が増えるため、重要です。

オブジェクト説明のためのディレクティブ

モジュールに含まれる機能を説明するのに使用するディレクティブもいくつもあります。それぞれのディレクティブは、説明対象に関する基本情報を記述するためのシグニチャが１つ以上あります。基本バージョンは全体インデックスにエントリーを追加します。インデックスのエントリーに追加する必要がなければ :noindex: フラグをディレクティブのオプションすれば回避することができます。以下の例はこのディレクティブのすべての機能を表すサンプルです:

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

   説明..

ディレクティブには以下のものがあります。

.. cfunction:: 型 名前(シグニチャ)

Cの関数の説明に使用します。シグニチャはC言語内で書かれる様に記述します。例えば以下のように書きます:

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

これは、関数のようなプリプロセッサマクロにも使用することができます。引き数名も書く必要があります。説明の中で使用されることもあります。

シグネチャ内のアスタリスクはバックスラッシュでエスケープする必要はありません。この中はreSTの行内のテキスト処理のパーサは実行されず、専用のパーサで処理されます。

.. cmember:: 型 名前

Cの構造体メンバーの説明をします。以下のように記述します:

.. cmember:: PyObject* PyTypeObject.tp_bases

説明のテキストには受け入れ可能な値の範囲、値がどのように解釈されるべきか、値が変更可能かどうかという情報を入れるべきです。関数のメンバーへの参照をテキストの中で書きたい場合には、 member ロールを使用すべきです。

.. cmacro:: 名前

“シンプルな”C言語のマクロの説明をします。シンプルなマクロというのは、単純なコード展開だけをするもので、引数を取ることはできません。また、単純な定数定義にも使用してはいけません。このディレクティブのサンプルを見るには、Pythonドキュメントの PyObject_HEAD, Py_BEGIN_ALLOW_THREADS を参照してください。

.. ctype:: 名前

C言語の型を説明します。シグニチャには型名を指定します。

.. cvar:: 型 名前

グローバルなC言語の変数について説明します。シグニチャは型を含む必要があります。以下のように記述します。

PyObject* PyClass_Type

.. data:: 名前

モジュール内のグローバルなデータの説明をします。変数も値も”定義された定数”として取り込むことができます。クラスとオブジェクトの属性はこの環境を使用してドキュメントを書くことはできません。

.. exception:: 名前

例外クラスの説明をします。シグニチャには、コンストラクタの引数を括弧付きで含めることもできますが、しなくてもかまいません。

.. function:: 名前(シグニチャ)

モジュールレベル関数の説明です。シグニチャはパラメータを含めます。オプションのパラメータに対してはカッコでくくります。分かりやすさを上げる目的でデフォルト値を入れることもできます。 シグニチャ の説明も参照してください。例:

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

オブジェクトのメソッドはこのディレクティブではドキュメントを記述することはできません。モジュールの名前空間にあり、モジュールの公開インタフェースとして作成されているメソッドに限って使用することができます。これらは通常の関数とほぼ同じようにしようできます。

説明にはパラメータに必要な関する情報と、それらがどのように使用されるのか(変更可能なオブジェクトが渡されたときに、変更されるのかどうか)、副作用、投げられる可能性のある例外の情報を含まなければなりません。小さいサンプルが提供されるでしょう。

.. class:: クラス名[(シグニチャ)]

クラスについて説明します。シグニチャにはコンストラクタ引数になるパラメータも含めることができます。 シグニチャ も参照してください。

このクラスに属する属性とメソッドのディレクティブはこのディレクティブの本体の中に記述します。このクラスの外に書いた場合は、提供された名前にクラス名が含まれていれば、クロスリファレンスは動作します。サンプル:

.. class:: Foo
   .. method:: quux()

-- あるいは --

.. class:: Bar

.. method:: Bar.quux()

最初の書き方が推奨です。

バージョン 0.4 で追加: 標準のreSTのディレクティブの class は、現在のSphinxでは cssclass という名前で提供されています。

.. attribute:: 名前

オブジェクトの属性のデータの説明をします。この説明には期待されるデータの型、値を直接変更することができるかどうか、という情報を含めます。

.. method:: 名前(シグニチャ)

オブジェクトのメソッドの説明をします。パラメータからは self パラメータははずします。この説明には function と同じ情報を記述するようにします。 シグニチャ も参照してください。

.. staticmethod:: 名前(シグニチャ)

method とほぼ一緒ですが、メソッドがスタティックメソッドであるということを表明します。

バージョン 0.4 で追加.

.. classmethod:: 名前(シグニチャ)

method とほぼ一緒ですが、メソッドがクラスメソッドであるということを表明します。

バージョン 0.6 で追加.

シグニチャ

関数やメソッド、クラスのコンストラクタのシグニチャは、オプションパラメータにカッコを使うのを除いて、Pythonで書くように記述することができます:

.. function:: compile(source[, filename[, symbol]])

このような省略可能な引数を表す場合には、慣習的にカンマの前に開きカッコを置きます。省略できる引数が二つ以上ある場合には、カッコを入れ子にするスタイルと、フラットにするスタイルの両方があります。このような場合にはほとんどの場合、オプションの引数は個別に与えることができます。

compile(source[, filename, symbol])

オプション引数のデフォルト値を与えることもできます。ただし、値にカンマが含まれると、シグニチャのパーサはうまく動作しません。Pythonの３つのスタイルの引数のアノテーションと同様に、返り値の型も記述することができます。

compile(source : string[, filename, symbol]) → ast object

詳細情報フィールドのリスト

バージョン 0.4 で追加.

オブジェクト説明のためのディレクティブの内側には、適切に情報が明示されたreSTフィールドを配置することができます。

• param, parameter, arg, argument, key, keyword: 引数の説明です。
• type: 引数のタイプです
• raises, raise, except, exception: この中から投げられる例外(いつ投げられるか？も)を定義します
• var, ivar, cvar: 変数の説明をします
• returns, return: 返り値の値について説明をします
• rtype: 返り値の型です。

フィールドは、 return, rtype 以外の場合は、上記のキーワードのうち、どれかと、引数を一つが引数として設定されています。 return, rtype だけは引数を取りません。サンプルを見ていただくのが一番でしょう:

.. function:: format_exception(etype, value, tb[, limit=None])

   トレースバック付きで、例外を人の読める形式にフォーマットします。

   :param etype: 例外のタイプ
   :param value: 例外オブジェクト
   :param tb: トレースバックオブジェクト
   :param limit: 表示するスタックフレームの数の最大数
   :type limit: 数値 or None
   :rtype: 文字列のリスト

これは以下のようにレンダリングされます:

format_exception(etype, value, tb[, limit=None])

トレースバック付きで、例外を人の読める形式にフォーマットします。

パラメタ:

• etype – 例外のタイプ
• value – 例外オブジェクト
• tb – トレースバックオブジェクト
• limit (数値 or None) – 表示するスタックフレームの数の最大数

戻り値の型:

文字列のリスト

コマンドラインのプログラムのマークアップ

コマンドラインのプログラムの説明を行うためのディレクティブについて紹介します:

.. cmdoption:: 名前 引数, 名前 引数, ...

コマンドラインオプション、もしくはスイッチについて説明をします。オプションの引き数名は不等号でくくる必要があります:

.. cmdoption:: -m <モジュール>, --module <モジュール>

   モジュールをスクリプトとみなして実行します

このディレクティブは 最初 のオプションを名前付きのターゲットとみなして、クロスリファレンスを作成します。これは option にて参照可能です。このサンプルの場合は、 :option:`-m` という形式でリンクを張ることができます。

.. envvar:: 名前

現在ドキュメントの対象ととなっているコードやプログラムが使用したり、定義する環境変数について説明します。

.. program:: 名前

currentmodule と同様に、このディレクティブ何も出力しません。その代わりにこのディレクティブを定義すると、Sphinxはこの後に定義される cmdoption ディレクティブが説明するオプションが、ここで指定された 名前 を持つプログラムに属するということを認識できるようになります。

program を使用する場合には、 option ロールとプログラム名を適合させる必要があります。以下のような状況について見てみます:

.. program:: rm

.. cmdoption:: -r

   再帰的に動作するようになります

.. program:: svn

.. cmdoption:: -r revision

   作業中のワークに対してリビジョンを設定します

この場合、 option`rm -r` 最初のオプションを示し、 option:`svn -r` は２番目のオプションを示します。

プログラム名はスペースを含むこともできます。そのため、 svn add や、 svn commit などのサブコマンドを個別に取り扱いたい、というケースにも対応できます。

バージョン 0.5 で追加.

説明のためのディレクティブのカスタマイズ

汎用的なバージョンのディレクティブも存在します:

.. describe:: テキスト

このディレクティブは上記で説明してきたようなディレクティブを使ったのと、同じ形式にフォーマットされたテキストを生成します。その代わり、インデックスのエントリーや、クロスリファレンスのターゲットは作成されません。これを使用するケースとしては、 ちょうどこのドキュメントで行っているように( ソースコードを表示 を参照)、ディレクティブ自身の説明を行いたい場合などに使用します:

.. describe:: opcode

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

拡張機能を使うと、このようなディレクティブを追加できます。詳しくは、 add_description_unit() メソッドのドキュメントをご覧ください。