reStructuredTextの仕様(ディレクティブ/role編)

ディレクティブ宣言

  • ディレクティブのtypeに許可される文字は以下のとおり。

    半角英数字および語中に含まれるハイフン、アンダースコア、ピリオドで構成された大文字・小文字を区別しない単語。連続した「ハイフン、アンダースコア、ピリオド」は互いに連続してはいけない。

    • ディレクティブに全角文字は使用できない。*1
  • 不正なtype宣言の場合、ディレクティブとみなされない(コメントとして処理される)。
  • 「::」の手前にスペース1つまでは書いて良い。
  • ディレクティブはトップレベル要素で終わる。

*1 : 仕様書上は「simple reference names」と書かれているものの、「simple reference names」では全角文字が使用できる。もっとも、「simple reference names」仕様書上では全角文字が使用できるとは書かれていない。おそらく期待される動作は「ディレクティブでも全角文字が使用できる」であり、実装上のミスと思われる。

ディレクティブオプション

  • オプション名もオプションの値も大文字・小文字を区別しない。
  • オプションの値が列挙されている場合、空の値を持つオプションはエラーとなる。
  • オプション名部分に日本語文字等を書くと、Pythonごと落ちる。
  • オプション名部分は「\」エスケープが有効
    	:o===pt--i\\=on=: これはオプション 
    	:no-option\: オプションではない 
    	:na\ m\e: nameオプションと解釈される
    	: name : オプションではない
    
  • オプション後に、オプションではない引数があるとエラーとなる。
    .. topic:: www
    	:class: eeee
    	error-string
    
  • classオプションは class="" 属性に展開される。
  • nameオプションは id="" 属性に展開される。
    • nameはリンクターゲット名となる。
    • nameと他のリンクターゲット名が重複した場合「Duplicate explicit target name」エラーとなる。
    • nameに使用できない文字(記号等)や全角文字が含まれる場合、その部分をハイフン(-)ひとつに置き換える。(例):name: xx@yy!!!zz → id="xx-yy-zz"
    • name中のバックスラッシュは評価されない。
    • name中の連続したスペースは1つのスペースに置き換えられる。

class指定

  • スペースで区切ることで、複数のクラスを指定できる。
  • 半角英数以外の文字が1つ以上連続した場合、ひとつの「-」に置き換えられる。
  • クラス名の先頭にある1つ以上の半角英字以外の文字は除去される。
    • スペースで区切られたクラス名それぞれについて判定される。
  • 大文字の半角英数は小文字に変換される。
  • これらの処理の結果、クラス指定が空文字となった場合や、そもそも値が空の時はエラーとなる。

image

  • 置換定義の image の align は top/middle/bottom のみ使用できる。
  • 置換定義ではない image の align はfigureと同一の仕様になる。
    • align の left/right はfloatオブジェクトとなる。
    • align の top/middle/bottom は指定するとエラーとなる。*2
  • width/height には小数を書いても良い。
  • scale は整数のみ。0でも良い。
  • target が見つからずエラーになった場合、altの文字列に対するリンクエラーを生成する。
    • alt文字列が指定されていない場合は、空文字に対するリンクエラーを生成する。

*2 : 仕様書にはbaselineの指定として使えると表記されている。

figure

  • <div class="figure" style="width:XXXXX">といったタグで展開される。

code

  • 未知の言語を指定するとエラーになる。
  • 引数に2つ以上(の言語)を指定するとエラーとなる。
  • number-linesオプションは負数でも良い。

math

  • classオプションは使用できない。
  • 引数は単に content の手前に展開される。
  • 本文部分に「\\」を含む時、本文部分は以下に展開される。
    \begin{split}
    本文
    \end{split}
    
  • 引数がある場合は以下に展開される。
    \begin{align}\begin{aligned}
    	引数部分 \\
    	\begin{split}
    		本分部分
    	\end{split}
    \end{aligned}\end{align}
    
    • このせいで、本文に \begin{eqnarray} 等があるTeX数式の表示に失敗する。
    • 引数があると、引数部分に式番号が出力される。
    • オプションがあるとたとえ空でも引数があるとみなされる。
    • mathディレクティブで引数(やオプション)を書くのは止めたほうが良い。
  • 引数のみの場合は単に「\[ 引数 \]」に展開される。
  • 引数も本文もない場合は、空の数式div環境が作られる。

unicode

  • 指定された文字は、概ね実体として展開される。
  • 置換対象の前後にはスペースが必要。
  • 置換対象の前後にあるスペースはいくつでも除去される。
  • 「..」によるコメントより後の行は(オプションを除き)無視される。

cvs-table

  • escape, delim, quoteに空文字を指定すると、Pythonごと落ちる。
    • スペースを指定する場合は U+20 等と記述する。
  • escape, delim, quoteオプションにすべて同じ文字を指定できる。
  • escape, delim, quoteオプションはheaderオプションには効かない。
  • escape文字を指定した場合でも、quote文字2個を連ねる("")エスケープは有効。
  • widthsオプションが指定されているとき、headerオプションを含めて最大カラム数がwidthsで指定した個数と同じでなければならない。
    • 超えても、少なくてもダメ。
  • widthsによる幅指定は、整数の%表記(四捨五入)に変換される。
  • headerオプションには複数行記述できる。
  • header-rows, stub-columnsには負数を指定できない。
  • header-rows, stub-columnsよりもデータが大きくなければならない。
    • 2行のテーブルでは、header-rowsは1か0しか許されない。
    • stub-columnsが1のとき、headerオプションを除くすべての行でカラムが2つ以上存在しなければならない。カラムが存在すれば中身は空でも良い。
      .. csv-table:: これはダメ
      	:stub-columns: 1
      
      	aaaa, bbbbb
      	cccc
      
      .. csv-table:: これは大丈夫
      	:stub-columns: 1
      
      	aaaa, bbbbb
      	,
      
  • quoteが終わった直後の文字は、headerオプションを除き行末か「,」でなければならない。
    .. csv-table:: エラーになる
    
    	"aaaa" , bbbb
    

contents

  • depthに負数を指定するとエラーになる。
  • depth=0 と 1 は同じ結果(トップレベル要素のみ表示)となる。
  • backlinks 省略時は entry と同じ。
  • 複数のcontentsディレクティブがあるとき、backlinksはそのタイトルエントリーに対して「最初の none でないもの」が有効
  • localが指定されていない場合、デフォルトタイトルとして「Contents」が展開される。
  • localを指定すると、localクラスが足される。
  • セクションが存在しない文章の最初でlocalを指定すると、クラス以外はlocalを指定しない場合と同じ結果。
  • 出力すべき内容がない時、タイトルもdivも出力されない。

sectnum

  • 存在する場所にかかわらず、そのファイル全体に影響を及ぼす。
  • 複数存在する場合、存在する数だけ同じ処理が行われる。
  • start, depth共に負数を指定できる。
  • depthが1以下の場合、トップレベル要素のみ作用する。
  • prefix, suffix内の記法はエスケープさ、「\」もそのまま出力される。

header, footer

  • htmlには何も出力されない。

target-notes

  • 有効なリンク参照をすべてfootnoteのように出力する。
  • 複数ある場合は、複数のリンクとバックリンクを出力する。

class

  • クラス名等がなぜか出力される。挙動が意味不明。
    .. class:: class-name
    .. class:: class-name2
    
    	てすと
    
    <dl class="class">
    <dt>
    <code class="descname">class-name</code></dt>
    <dd></dd></dl>
    
    <em class="property">class </em><code class="descname">class-name2</code></dt>
    <dd><p>てすと</p></dd></dl>
    
  • Sphoinxのマニュアルによれば、rst-class を使えということらしい。
    デフォルトドメインに class ディレクティブが存在するため、このディレクティブはそのままでは使用できません。そのため、Sphinxでは、 rst-class という名前で再定義しています。
    

default-role

  • 何も指定していない場合 :title: がデフォルトとなる。
  • その場所以降、次の default-role が出てくるまでの間のリテラルに対して有効。
  • 空のroleを指定した場合、デフォルトのrole(:title:)が選択される。
  • 未知(未定義)のroleを指定した場合、default-roleの指定自体が無効となる。
    • その直前に指定されているものが、有効となる。
    • 未定義のroleを指定して、後からそのroleを定義した場合も、同じ挙動(無効)となる。

role

  • role名が規定の文字列でない場合、roleと認識されない。
    • 「ロール名は英数字と内部に独立した『- _ + : .』」
  • role名は、すべて小文字に変換され参照される。
  • roleは :role:`xxx` 形式であること。以下は無効。
    - :strong: `文字`
    - :strong:``文字``
    - :strong:文字
    
  • roleと参照 _ の両方があるとエラーになる。
    - :strong:`エラー`_
    - :strong:`エラー`__
    - `エラー`:strong:_
    - :strong:`エラー`:strong:__
    - `有効な参照`_:void-role:
    - `有効な参照`__:void-role:
    
  • :pep: :rfc: は省略形を使うと、リンク部が太字(strong)になる。
  • :pep: :rfc: は整数以外を指定するとエラーとなる。ただし負数を指定しても良い。
  • 存在するroleでエラーが発生した場合、その部分は何も出力されない。
  • :raw: の format は大文字小文字を区別する。*3
  • :code: で未知のlanguageを指定するとエラーになる。

*3 : ディレクティブのrawは区別しない。バグだと思われる。

roleディレクティブ(role定義)

  • 新しいrole名が正しくない場合エラーとなる。
  • 継承元role名が見つからない場合エラーとなる。
  • emphasisやstrong等、組み込み済のroleも再定義できる。
  • role名を大文字でも定義できるが、参照できないクラスになる。*4
    • 継承元としても参照できない。以下は最初の定義以外すべてエラーとなる。
      .. role:: UPPER
      .. role:: err (UPPER)
      
      :upper:`test` :UPPER:`test` :err:`test` 
      
  • 自分自身を継承元として再定義できる。
    .. role:: strong ( strong )
    	:class: XXX
    
  • 置換定義中にrole参照が存在した場合、置換定義を行った時点でのroleを参照する。
    • default-roleについても同様。置換定義を行った時点でのdefault-roleを参照する。
  • class以外の(存在する)オプションの正当性は、定義時ではなく使用時(評価時)に評価される。

classの挙動

  • classオプションを指定しない場合、定義role名がclassオプションに指定されたものとみなされる。
  • もしrole名がclass名として許されない形式(数字のみ等)で、classオプションも指定されていない場合、role定義自体がエラーとなる。
    .. role: new-class
    .. role: 123456
    
    :new-class:`新しいクラス`
    → <span class="new-class">新しいクラス</span>
    
  • role が元々classを持っている場合(literalやmath等)、classオプションを指定するとそのクラスを追加で出力する。
    • 多重継承した場合、継承元のオプションは一切引き継がない。
    • オリジナル(大元)のroleやclassは引き継ぐ。

*4 : おそらくバグだと思われる

OK キャンセル 確認 その他