reST ディレクティブ編¶

ディレクティブ(ref <directives>)は汎用の明示的マークアップです。reSTの拡張のためのメカニズムの一つで、ロールが指定されることがあります。Sphinxはこのディレクティブをかなり多用しています。

Docutilsは次のようなディレクティブを含みます:

• 忠告: attention, caution, danger, error, hint, important, note, tip, warning ,および、一般的な用途の admonition. (ほとんどのテーマは、"note"と"warning"にだけスタイルを適用します)

• イメージ:

  • image
  • figure (キャプション、反例を含むイメージ)

• 追加の本体要素:

  • contents (現在のファイル内だけの目次)
  • container (カスタムのクラスを付加できるコンテナ。HTMLで外部の <div> を生成するのに便利)
  • rubric (ドキュメントのセクションと関係のない見出し)
  • topic, sidebar (特別に強調されたなボディ要素)
  • parsed-literal (インラインマークアップをサポートしたリテラルブロック)
  • epigraph (追加の属性行を付加できるブロック引用)
  • highlights, pull-quote (特有のクラス属性を持つブロック引用)
  • compound (複合パラグラフ)

• 特別なテーブル:

  • table (タイトル付きのテーブル)
  • csv-table (カンマ区切りの値からテーブル生成)
  • list-table (リストのリストからテーブル生成)

• 特別なディレクティブ:

  • raw (ターゲットの書式のマークアップを挿入)
  • include (他のファイルからreStructuredTextを取り込み) -- Sphinxでは、絶対パスが指定されると、ソースディレクトリからの相対パスが利用されます。
  • class (次の要素へのクラス属性の設定)

• HTML定義

  • meta (HTMLの <meta> タグの生成)
  • title (ドキュメントのタイトルの上書き)

• 疑似命令マークアップ:

  • default-role (デフォルトのロールをセット)
  • role (新しいロールの作成)

  これらのマークアップの影響範囲は、そのマークアップが書かれたファイルだけに限定されるため、Sphinxが提供する default_role を設定する方が良いでしょう。

sectnum, header, footer の3つのディレクティブは使用 しない で下さい。

Sphinxによって追加されたディレクティブに関しては sphinxmarkup を参照してください。

基本的に、ディレクティブは名前、引数、オプション、コンテンツなどで構成されています。これらの用語を覚えておいてください。これらは次の章でカスタムディレクティブの紹介を行う際に利用します。以下にサンプルを示します:

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   ユーザから入力されたテキストのうち、１行を返します。

function がディレクティブの名前です。ここでは二つの引数が与えられています。1行目の残りの部分と、2行目が引数です。そして1つのオプション module も同様に設定されています。見ての通り、オプションは引数のある行のすぐ次の行に書かれていています。そして、目印としてコロンが付いています。オプションは、ディレクティブのコンテンツと同じインデントの高さにします。

ディレクティブのコンテンツというのは、空白行の後に続くブロックで、ディレクティブが開始された地点よりも深いインデントでくくられています。

.. directive-name:: argument1
                    argument2
   :option: value

   コンテンツ

samples¶

画像(img)¶