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

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

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

.. 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:: 名前(シグニチャ)

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

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

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

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

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

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

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

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

-- あるいは --

.. class:: Bar

.. method:: Bar.quux()

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

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

.. attribute:: name

Describes an object data attribute. The description should include information about the type of the data to be expected and whether it may be changed directly.

.. method:: name(signature)

Describes an object method. The parameters should not include the self parameter. The description should include similar information to that described for function. See also Signatures.

.. staticmethod:: name(signature)

Like method, but indicates that the method is a static method.

バージョン 0.4 で追加.

.. classmethod:: name(signature)

Like method, but indicates that the method is a class method.

バージョン 0.6 で追加.

Signatures

Signatures of functions, methods and class constructors can be given like they would be written in Python, with the exception that optional parameters can be indicated by brackets:

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

It is customary to put the opening bracket before the comma. In addition to this “nested” bracket style, a “flat” style can also be used, due to the fact that most optional parameters can be given independently:

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

Default values for optional arguments can be given (but if they contain commas, they will confuse the signature parser). Python 3-style argument annotations can also be given as well as return type annotations:

.. function:: compile(source : string[, filename, symbol]) -> ast object

Info field lists

バージョン 0.4 で追加.

Inside description unit directives, reST field lists with these fields are recognized and formatted nicely:

• param, parameter, arg, argument, key, keyword: Description of a parameter.
• type: Type of a parameter.
• raises, raise, except, exception: That (and when) a specific exception is raised.
• var, ivar, cvar: Description of a variable.
• returns, return: Description of the return value.
• rtype: Return type.

The field names must consist of one of these keywords and an argument (except for returns and rtype, which do not need an argument). This is best explained by an example:

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

   Format the exception with a traceback.

   :param etype: exception type
   :param value: exception value
   :param tb: traceback object
   :param limit: maximum number of stack frames to show
   :type limit: integer or None
   :rtype: list of strings

This will render like this:

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

Format the exception with a traceback.

パラメタ:

• etype – exception type
• value – exception value
• tb – traceback object
• limit (integer or None) – maximum number of stack frames to show

戻り値の型:

list of strings

Command-line program markup

There is a set of directives allowing documenting command-line programs:

.. cmdoption:: name args, name args, ...

Describes a command line option or switch. Option argument names should be enclosed in angle brackets. Example:

.. cmdoption:: -m <module>, --module <module>

   Run a module as a script.

The directive will create a cross-reference target named after the first option, referencable by option (in the example case, you’d use something like :option:`-m`).

.. envvar:: name

Describes an environment variable that the documented code or program uses or defines.

.. program:: name

Like currentmodule, this directive produces no output. Instead, it serves to notify Sphinx that all following cmdoption directives document options for the program called name.

If you use program, you have to qualify the references in your option roles by the program name, so if you have the following situation

.. program:: rm

.. cmdoption:: -r

   Work recursively.

.. program:: svn

.. cmdoption:: -r revision

   Specify the revision to work upon.

then :option:`rm -r` would refer to the first option, while :option:`svn -r` would refer to the second one.

The program name may contain spaces (in case you want to document subcommands like svn add and svn commit separately).

バージョン 0.5 で追加.

Custom description units

There is also a generic version of these directives:

.. describe:: text

This directive produces the same formatting as the specific ones explained above but does not create index entries or cross-referencing targets. It is used, for example, to describe the directives in this document. Example:

.. describe:: opcode

   Describes a Python bytecode instruction.

Extensions may add more directives like that, using the add_description_unit() method.