adiaryマニュアル

• ディレクティブ宣言
• ディレクティブオプション
  • class指定
• image
• figure
• code
• math
• unicode
• cvs-table
• contents
• sectnum
• header, footer
• target-notes
• class
• default-role
• role
• roleディレクティブ（role定義）
  • classの挙動

ディレクティブ宣言

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

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

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

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

• オプション名もオプションの値も大文字・小文字を区別しない。
• オプションの値が列挙されている場合、空の値を持つオプションはエラーとなる。
• オプション名部分に日本語文字等を書くと、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文字列が指定されていない場合は、空文字に対するリンクエラーを生成する。

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を指定するとエラーになる。

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は引き継ぐ。