標準ドメイン¶

Added in version 1.0.

標準ドメインには、固有のドメインを作るまでもないすべてのマークアップが含まれます。これらのディレクティブやロールには、ドメイン名のプリフィックスは付きません。

標準ドメインには、 add_object_type() APIを使って追加されたカスタムの説明ディレクティブ、ロールも含まれます。

現在は、コマンドラインのプログラムを説明するためのディレクティブ群が提供されています:

.. option:: name args, name args, ...¶

コマンド・ライン引数またはスイッチを説明します。オプションの引数名は括弧で囲む必要があります。例えば:

.. option:: dest_dir

   Destination directory.

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

   Run a module as a script.

The directive will create cross-reference targets for the given options, referenceable by option (in the example case, you'd use something like :option:`dest_dir`, :option:`-m`, or :option:`--module`).

バージョン 5.3 で変更: One can cross-reference including an option value: :option:`--module=foobar`, ,``:option:--module[=foobar]`` or :option:`--module foobar`.

Use option_emphasise_placeholders for parsing of "variable part" of a literal text (similarly to the samp role).

cmdoption directive is a deprecated alias for the option directive.

.. confval:: name¶

Describes a configuration value or setting that the documented code or program uses or defines. Referenceable by confval.

:type: (text)¶: Describes the type of the configuration value. This is optional, and if specified will be interpreted as reStructuredText.

:default: (text)¶: Describes the default value of the configuration value. This is optional, and if specified will be interpreted as reStructuredText.

例:

.. confval:: the_answer
   :type: ``int`` (a *number*)
   :default: **42**

   This is a setting that controls the value of the answer.

will be rendered as follows:

the_answer¶

Type:: int (a number)
Default:: 42

This is a setting that controls the value of the answer.

.. envvar:: name¶: Describes an environment variable that the documented code or program uses or defines. Referenceable by envvar.

.. program:: name¶

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

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

.. program:: rm

.. option:: -r

   Work recursively.

.. program:: svn

.. option:: -r <revision>

   Specify the revision to work upon.

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

If None is passed to the argument, the directive will reset the current program name.

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

Added in version 0.5.

どこのドメインにも属さないような、非常に汎用的なオブジェクトの説明用のディレクティブも存在します:

.. describe:: text¶

.. object:: text¶

このディレクティブはドメインで提供されているディレクティブを使ったのと、同じ形式にフォーマットされたテキストを生成します。その代わり、インデックスのエントリーや、クロスリファレンスのターゲットは作成されません:

.. describe:: PAPER

   You can set this variable to select a paper size.