reStructuredText ディレクティブ

Author:David Goodger
Contact:docutils-develop@lists.sourceforge.net
Revision:$Revision: 7882 $
Date:$Date: 2015-04-20 10:55:19 +0000 (Mon, 20 Apr 2015) $
Copyright:

このドキュメントは、パブリック ドメインで公開されています。

このドキュメントはreStructuredTextのパーサ(文書解析器)で実装しているディレクティブについて記述しています。

ディレクティブは以下の構文で記述されます:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

ディレクティブは明示的な開始記号(ピリオド2文字とスペース1文字)で始まり、その後ろにディレクティブのタイプと2つのコロンが続きます(合わせて"ディレクティブマーカー"と言います)。ディレクティブブロックはディレクティブマーカーの直後に続く、インデントされた全ての行で構成されます。ディレクティブブロックの内部は複数の 引数・オプション(フィールドリスト)・コンテンツで構成されます。詳しい構文については、 reStructuredText 言語仕様書(reStructuredText Markup Specification)のディレクティブ(Directive)節を参照してください。

後で述べる "doctree エレメント" (ドキュメントツリーエレメント名: XML DTD 標準記述子) リストが個々のディレクティブに対応します。エレメント階層の詳細については、 The Docutils Document TreeDocutils Generic DTD XML ドキュメントタイプ定義 を参照してください。また、ディレクティブの実装の詳細については、reStructuredTextディレクティブの作り方(Creating reStructuredText Directives)を参照してください。

警告

警告の仕様

Directive Types:
 "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning", "admonition"
Doctree Elements:
 attention, caution, danger, error, hint, important, note, tip, warning, admonition, title
Directive Arguments:
 None.
Directive Options:
 :class:, :name:
Directive Content:
 

本文エレメントとして解釈される

警告(Admonitions)は "topics" の拡張版で、他のディレクティブの本文に記述することが出来ます。大抵の 警告はドキュメント内のオフセットブロックとして表示され、時には外枠や影付きで表示されます。表示されるタイトルは警告の種類によって決定されます。例えば:

.. DANGER::
   Beware killer rabbits!

このディレクティブはおそらく以下のように表示されます:

+------------------------+
|        !DANGER!        |
|                        |
| Beware killer rabbits! |
+------------------------+

以下の警告ディレクティブが実装されています。

  • attention
  • caution
  • danger
  • error
  • hint
  • important
  • note
  • tip
  • warning

ディレクティブの直後に記述したテキスト(同じ行 And/Or 次の行以降のインデントされたテキスト)はディレクティブブロックとして解釈され、テキストは普通の本文エレメントとして解釈されます。例えば、以下の "note" という警告ディレクティブは1つのパラグラフと2つのリストアイテムを含む1つのリストブロックとして解釈されます:

.. note:: This is a note admonition.
   This is the second line of the first paragraph.

   - The note contains all indented body elements
     following.
   - It includes this bullet list.

一般的な警告

Directive Type:"admonition"
Doctree Elements:
 admonition, title
Directive Arguments:
 

1つ必須 (警告のタイトル)

Directive Options:
 

指定可能、以下を参照.

Directive Content:
 

本文エレメントとして解釈される

これは一般的なタイトル付き警告です。タイトルは書き手が任意に決めることが出来ます。

書き手が指定したタイトルも"class"属性値として使用されます("admonition-" が接頭され、小文字に統一され、ローマ字・数字以外の文字はハイフンに変換されます)。以下の警告の例は:

.. admonition:: And, by the way...

   You can make up your own admonition too.

以下のドキュメントツリーに変換されます(pseudo-XML):

<document source="test data">
    <admonition classes="admonition-and-by-the-way">
        <title>
            And, by the way...
        <paragraph>
            You can make up your own admonition too.

一般的なオプション(common options)を使用出来ます:

class : text

自動生成の "classes" 属性を上書きします。

name : text

admonition エレメントの "names" 属性に指定された text を追加します。

画像

画像に関する二つのディレクティブ "image" と "figure" があります。

Image

Directive Type:"image"
Doctree Element:
 image
Directive Arguments:
 

1つ必須 (画像のURI)

Directive Options:
 

指定可能

Directive Content:
 None.

"image" はシンプルな画像です:

.. image:: picture.png

インライン画像は "image" ディレクティブを substitution definition 内で使用して定義できます。

画像の参照先を示すURLをディレクティブの引数に指定する必要があり、これはハイパーリンクとして利用されます。URIはディレクティブ開始行と同じ行に記述するか、以下に示すようにインデントされたテキストブロックに空白行を挟まずに記述します。もし、URIが複数行にまたがってしまった場合は、各行の行頭・行末の空白を除いて連結されます。

オプションとして、以下のフィールドリストに示す image options を指定することが出来ます:

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right

以下のオプションを使用出来ます:

alt : text

代替テキスト: 短い画像の説明文。アプリケーションが画像を表示出来ない場合、あるいは音声読み上げに使用されます。

height : length

画像の縦幅をピクセルで指定し、予約領域や画像の縦方向の拡大縮小に使用されます。"scale" オプションと組み合わせて使用することが出来ます。例えば、heightに200、scaleに50が指定された場合、高さ100で拡大縮小無しと評価されます。

width : length か、その行の幅に対する percentage : length or percentage of the current line width

画像の横幅をピクセルで指定し、予約領域や画像の横方向の拡大縮小に使用されます。前述の "height" や "scale" と組み合わせて使用することが出来ます。

scale : 比率を整数で指定 ( "%" 記号を付けても良い) : integer percentage (the "%" symbol is optional)

縦横同比率で画像を拡大縮小します。デフォルトは "100 %" で、拡大縮小なしです。

もし、"height" や "width" が指定されていない場合、 Python Imaging Library (PIL) がインストールされていれば、画像ファイルから幅や高さを取得して使用します。

align : "top", "middle", "bottom", "left", "center", "right" いずれか : "top", "middle", "bottom", "left", "center", or "right"

画像の配置はHTMLの <img> タグの "align" 属性として評価されます。"top", "middle", "bottom" の3つは縦方向の配置位置を(テキストのベースラインからの相対位置で)コントロールします(これらは画像がインラインで使用される場合にのみ有効です)。"left", "center", "right" の3つは横方向の配置位置をコントロールします。この指定は画像をfloat指定にし、文字列を回り込みさせます。これらの指定はブラウザや表示するソフトウェアによって表示方法が異なります。

target : text (URI もしくは参照名) : text (URI or reference name)

画像をハイパーリンクとしてクリック可能にします。オプションの引数にはURI(絶対パス/相対パス)か、アンダースコアを接尾した参照名 (例: name_) を指定出来ます。

他に共通のオプションとして :class::name: があります。

Figure

Directive Type:"figure"
Doctree Elements:
 figure, image, caption, legend
Directive Arguments:
 

1つ必須 (画像のURI)

Directive Options:
 

指定可能

Directive Content:
 

キャプションと凡例(オプション)として解釈される

"figure" は image options を含む Image データで構成され、単一パラグラフのキャプションと凡例を含めることが出来ます。For page-based output media, figures might float to a different position if this helps the page layout.

.. figure:: picture.png
   :scale: 50 %
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).

   The legend consists of all elements after the caption.  In this
   case, the legend consists of this paragraph and the following
   table:

   +-----------------------+-----------------------+
   | Symbol                | Meaning               |
   +=======================+=======================+
   | .. image:: tent.png   | Campground            |
   +-----------------------+-----------------------+
   | .. image:: waves.png  | Lake                  |
   +-----------------------+-----------------------+
   | .. image:: peak.png   | Mountain              |
   +-----------------------+-----------------------+

キャプションパラグラフや凡例の前には空行が必要です。キャプションを書かずに凡例を書く場合は、キャプションの代わりに空のコメント ("..") を書きます。

"figure" ディレクティブは "image" ディレクティブの全てのオプションをサポートしています(image options を参照)。それらのオプション("align"を除く)は内包するimageに渡されます。

align : "left", "center", "right" いずれか : "left", "center", or "right"

横方向の配置位置をコントロールします。この指定は画像をfloat指定にし、文字列を回り込みさせます。これらの指定はブラウザや表示するソフトウェアによって表示方法が異なります。

さらに以下のオプションを指定することが出来ます:

figwidth : "image", length, または現在行の幅に対する percentage : "image", length, or percentage of current line width

figureの最大幅をピクセルで記述します。または "image" を記述することも出来、この場合画像の幅が利用されます( Python Imaging Library が必要です)。もし画像ファイルが見つからなかったり、必要なソフトウェアが提供されていない場合、このオプションは無効です。

"figure" Doctree エレメントの "width" 属性をセットしてください。

このオプションは含まれる画像の伸縮を行いません。その用途には Image オプションの"width"を以下のように使用してください:

+---------------------------+
|        figure             |
|                           |
|<------ figwidth --------->|
|                           |
|  +---------------------+  |
|  |     image           |  |
|  |                     |  |
|  |<--- width --------->|  |
|  +---------------------+  |
|                           |
|The figure's caption should|
|wrap at this width.        |
+---------------------------+
figclass : text

figureエレメントの "classes" 属性を指定します。 class ディレクティブを参照してください。

本文エレメント

Topic

Directive Type:"topic"
Doctree Element:
 topic
Directive Arguments:
 

1つ必須 (トピックのタイトル)

Directive Options:
 :class:, :name:
Directive Content:
 

トピックの本文として解釈される

トピックはタイトル付きのBlock Quote、あるいはセルフコンテインドでサブセクションを持たないセクションに似ています。"topic"ディレクティブをドキュメントの回り込み設定から独立したものとして使えます。トピックはセクションのどこにでも記述することが出来ます。本文エレメントとトピックはネストしたトピックを持ちません。

このディレクティブの唯一の引数は、トピックのタイトルになります。タイトルと本文の間は必ず1行空けてください。インデントされた後続の行は全てトピックの本文となり、本文エレメントとして解釈されます。例:

.. topic:: Topic Title

    Subsequent indented lines comprise
    the body of the topic, and are
    interpreted as body elements.

行ブロック

非推奨

"line-block" ディレクティブは非推奨になりました。代わりに line block syntax を使用してください。

Directive Type:"line-block"
Doctree Element:
 line_block
Directive Arguments:
 None.
Directive Options:
 :class:, :name:
Directive Content:
 

行ブロックの本文になります。

"line-block" ディレクティブは、改行や、最初のインデントが重要な行、インラインマークアップがサポートされている行の要素を構築します。 解釈済みリテラルブロック と同等ですが、出力は異なります: 通常、タイプライター/等幅フォントではなく、普通のSerif書体で、自動的にインデントされません(line-blockディレクティブをブロッククォートで始めればインデントされた行ブロックとなります)。行ブロックは行の構造が重要な住所、詩(歌詞)などに適しています。以下に古典的な例を紹介します:

"To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
Ewan McTeagle (for Lassie O'Shea):

    .. line-block::

        Lend us a couple of bob till Thursday.
        I'm absolutely skint.
        But I'm expecting a postal order and I can pay you back
            as soon as it comes.
        Love, Ewan.

解釈済みリテラルブロック

Directive Type:"parsed-literal"
Doctree Element:
 literal_block
Directive Arguments:
 None.
Directive Options:
 :class:, :name:
Directive Content:
 

リテラルブロックの本文になります。

通常のリテラルブロックとは異なり、 "parsed-literal" ディレクティブはインラインマークアップを解析してリテラルブロックを構築します。 行ブロック と同じですがレンダリング部分は異なり、通常のリテラルブロックのようなタイプライター/等幅フォント書体で表示します。解釈済みリテラルブロックは、コード例の中にハイパーリンクを追加するのに有用です。

ただし、テキストがインラインマークアップとして認識され、解釈されることには注意が必要です。もし解釈されたくない場合は、バックスラッシュによるエスケープを行う必要があります。そして、マークアップ用の文字列は解釈時点で取り除かれるため、縦方向の整列に対してケアが必要です。解釈された "アスキーアート" はトリッキーで、余分な空白文字が必要になる場合があります。

たとえば、以下のテキストにある全ての要素名はリンクになります:

.. parsed-literal::

   ( (title_, subtitle_?)?,
     decoration_?,
     (docinfo_, transition_?)?,
     `%structure.model;`_ )

コード

Directive Type:"code"
Doctree Element:
 literal_block, inline elements
Directive Arguments:
 

1つ、オプション(フォーマット言語)

Directive Options:
 name, class, number-lines.
Directive Content:
 

リテラルブロックの本文になります。

Configuration Setting:
 syntax_highlight.

(Docutils 0.9から追加)

"code" ディレクティブはリテラル ブロックを構築します。コードの言語が指定された場合、コンテンツは Pygments シンタックスハイライトによって解釈され、各単語は inline elements エレメントn中に各単語のカテゴリに沿ったclass属性付きで格納されます。実際のハイライト表示のためにはスタイル シートが必要です (例: generated by Pygments, と sandbox/stylesheets を参考にしてください)。

解析するかどうかは設定の syntax_highlight とコマンドラインオプションで指定するか、ディレクティブの引数を空にして代わりに :class: オプションに言語を指定します。これはまた、 Pygments がインストールされていないか、または指定した言語が supported languages and markup formats. の中に無い場合の警告を防ぎます。

インラインコードについては "code" role を使用します。

以下のオプションを使用出来ます:

number-lines : [開始行番号] : [start line number]

各行の最初に行番号を出力します。引数は省略可能で、行番号を指定出来ます (デフォルトは1)。

他に共通のオプションとして :class::name: があります。

例:

以下のディレクティブの内容:

.. code:: python

  def my_function():
      "just a test"
      print 8/2

は、Pythonソースコードとして解析され出力されます。

数式

Directive Type:"math"
Doctree Element:
 math_block
Directive Arguments:
 

1つ、オプション: コンテンツの前に追加する文字列

Directive Options:
 :class:, :name:
Directive Content:
 Becomes the body of the math block. (Content blocks separated by a blank line are put in adjacent math blocks.)
Configuration Setting:
 math_output

(Docutils 0.8から追加)

"math" ディレクティブは数学的なコンテンツ(数式や方程式)ブロックをドキュメントに挿入します。入力フォーマットは LaTeXの数式文法[1] で、Unicodeシンボルも利用できます。例:

.. math::

  α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)

Support is limited to a subset of LaTeX math by the conversion required for many output formats. For HTML, the math_output configuration setting (or the corresponding --math-output command line option) select between alternative output formats with different subsets of supported elements. If a writer does not support math typesetting at all, the content is inserted verbatim.

[1]

サポートしている LaTeX コマンドにはAMS拡張が含まれます(参照: Short Math Guide)。

For inline formulas, use the "math" role.

注釈

Directive Type:"rubric"
Doctree Element:
 rubric
Directive Arguments:
 

1つ必須 (注釈テキスト)

Directive Options:
 :class:, :name:
Directive Content:
 None.

rubric n. 1. 原稿、本、法令のなかのタイトル、見出し。赤字や本文テキストよりも目立つように書かれている。

—Random House Webster's College Dictionary, 1991

"rubric" ディレクティブは "rubric" エレメントを1つ、ドキュメントツリーに挿入します。注釈(rubric)は非形式的な見出しで、ドキュメントの構造とは一致しません。

引用句

Directive Type:"epigraph"
Doctree Element:
 block_quote
Directive Arguments:
 None.
Directive Options:
 None.
Directive Content:
 

引用ブロックの本文として解釈される

引用句は短い題字や引用、詩など、ドキュメントやセクションの始めに使うのに適しています。

"epigraph" ディレクティブは "epigraph"-classのついた引用ブロックを生成します。例えばこの入力では:

.. epigraph::

   No matter where you go, there you are.

   -- Buckaroo Banzai

以下のようなドキュメントツリー片になります:

<block_quote classes="epigraph">
    <paragraph>
        No matter where you go, there you are.
    <attribution>
        Buckaroo Banzai

ハイライト

Directive Type:"highlights"
Doctree Element:
 block_quote
Directive Arguments:
 None.
Directive Options:
 None.
Directive Content:
 

引用ブロックの本文として解釈される

ハイライトはドキュメントまたはセクションの要点をまとめたもので、多くの場合リストで構成されます。

"highlights" ディレクティブは "highlights"-classのついた引用ブロックを生成します。類似の例として前述の 引用句 を参照して下さい。

Pull-Quote

Directive Type:"pull-quote"
Doctree Element:
 block_quote
Directive Arguments:
 None.
Directive Options:
 None.
Directive Content:
 

引用ブロックの本文として解釈される

pull-quoteは、「取り出してクォートした」小さなテキストの集まりで、通常、他より大きな書体で書かれます。pull-quoteは長い記事で特に注目すべき点を書くのに使います。

"pull-quote" ディレクティブは "pull-quote"-classのついた引用ブロックを生成します。類似の例として前述の 引用句 を参照して下さい。

複合段落

Directive Type:"compound"
Doctree Element:
 compound
Directive Arguments:
 None.
Directive Options:
 :class:, :name:
Directive Content:
 

本文エレメントとして解釈される

(Docutils 0.3.6で追加)

"複合"ディレクティブは複合段落を作るのに使われます。複合段落は論理的な1つの段落で、中にシンプルな段落、リテラル ブロック、テーブル、リストなどの複数の物理的なボディ要素を含みます。テキストやインライン要素を直接は含みません。例:

.. compound::

   The 'rm' command is very dangerous.  If you are logged
   in as root and enter ::

       cd /
       rm -rf *

   you will erase the entire contents of your file system.

上記の例では、リテラルブロックが物理的な段落に埋め込まれていて、その次にまた別の段落が続いています。

注釈

"compound"ディレクティブはHTMLでいう <div> エレメントのような一般的なブロックレベルコンテナ ではありません 。これを連続したエレメントをグルーピングするために使うと期待しない結果となることがあるため、そのような目的で使わないでください。

もし、一般的なブロックレベルコンテナが必要であれば、次に説明する container ディレクティブを使って下さい。

複合段落は、異なるテキストブロックの集まりですが、通常、論理的に単一であることを強調するように配置されます:

  • もし段落の先頭がインデントされるようにレンダリングされる場合、複合段落ではそのなかに含まれる最初の物理段落要素だけがインデントされ、2番目以降はインデントされないべきです;

  • 物理エレメントの行間は縮小されることがあります;

  • 他にも色々。

コンテナ

Directive Type:"container"
Doctree Element:
 container
Directive Arguments:
 

1つ以上、オプション(class名)

Directive Options:
 :name:
Directive Content:
 

本文エレメントとして解釈される

(Docutils 0.3.10から追加)

"container" ディレクティブはその中のコンテンツ(任意の本文エレメント)の周りを囲む、どこでも使用できるブロックレベルの "container" エレメントです。"classes" 属性の値(複数)はディレクティブの引数で与えられます。これはユーザーとアプリケーション向けの拡張メカニズムです。例:

.. container:: custom

   This paragraph might be rendered in a custom way.

上記を解釈した結果は以下のような疑似XMLとして表されます:

<container classes="custom">
    <paragraph>
        This paragraph might be rendered in a custom way.

"container" ディレクティブはHTMLの <div> エレメントと等価です。これは、連続したエレメントをグルーピングするために、ユーザーやアプリケーションの何かの目的のために使用できます。

テーブル

テーブルをちゃんと表現するには、reStructuredTextのテーブル記法だけでは少し情報が不足しています。 table ディレクティブでテーブルにタイトルを付けられるでしょう。reStructuredText のテーブル記法では書きにくいことがあったり、テーブルに使いたいデータが既にCSVフォーマットで用意されていたりするなら、 csv-table ディレクティブを使うと良いでしょう。

Table

Directive Type:"table"
Doctree Element:
 table
Directive Arguments:
 

1つ、省略可(テーブルタイトル)

Directive Options:
 :class:, :name:
Directive Content:
 

標準のreStructuredTextテーブル記法。

(Docutils 0.3.1で追加)

"table"ディレクティブはテーブルにタイトルを付けるために使用されます:

.. table:: Truth table for "not"

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

CSVテーブル

Directive Type:"csv-table"
Doctree Element:
 table
Directive Arguments:
 

1つ、省略可(テーブルタイトル)

Directive Options:
 

指定可能、以下を参照.

Directive Content:
 

CSV (カンマ区切りの値) テーブル

警告

"csv-table"ディレクティブの":file:"と ":url:" オプションは、潜在的なセキュリティ ホールとなる可能性があります。これらのオプションは "file_insertion_enabled" 実行設定で無効にできます。

(Docutils 0.3.4で追加)

"csv-table" ディレクティブは、CSV (コンマ区切り値) データからテーブルを作成します。CSVはデータベースやスプレッドシートアプリケーションによって生成される一般的なデータ形式です。CSVデータはドキュメント内にも書けますし、別ファイルからも読み込めます。

例:

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

複数行のブロック記法と、インライン記法の両方をセル内に書けます。マークアップの途中であれば行の終わりが来てもセルの終了にはなりません。

動作の制約:

  • 行ごとの列数が同じかどうかをチェックする仕組みはありません。代わりに、一部のジェネレータが出力するような、短い行の末尾に空のセルを挿入していないCSVもサポートしています。その場合、短い行の末尾に自動的に空のセルを追加します。

[2]

空白区切り記号は、外部CSVファイルでのみサポートされます。

[3](1, 2, 3)

Python2では、 delimiter, quote, escape オプションの値にはASCII文字のみ使用できます(PythonのcsvモジュールがUnicodeや、utf-8にエンコードされた全ての非ASCIIなマルチバイト文字列をサポートしていないためです)。この制限はPython3にはありません。

以下のオプションを使用出来ます:

widths : 数値 [, 数値...] : integer [, integer...]

コンマまたはスペースで区切られた、相対列幅のリスト。デフォルトでは幅の等しい列 (100%/#columns)です。

header-rows : 数値 : integer

テーブルのヘッダーとして使用するCSV形式データ行数です。デフォルトは0です。

stub-columns : 数値 : integer

スタブ(行の左のタイトル列)として使用するテーブル列の数です。デフォルトは0です。

header : CSV data

CSVデータから読み込む header-rows の値とは独立した追加のテーブルヘッダーデータで、 header-rows よりも前に追加されます。使用するメインのCSVデータと同じフォーマットを使う必要があります。

file : 文字列(改行は取り除かれます) : string (newlines removed)

CSVデータファイルのローカルファイルシステムパス。

url : 文字列 (空白は取り除かれます) : string (whitespace removed)

CSVデータファイルが置かれているインターネットのURL。

encoding : テキストのエンコーディング名 : name of text encoding

外部のCSVデータ(ファイルまたはURL)のテキストエンコーディングです。デフォルトはドキュメントのエンコーディング(指定されている場合)を使用します。

delim : 1文字 | "tab" | "space" [] : char | "tab" | "space" [2]

区切り文字を表す1文字[3] で、フィールドを区切るのに使われます。デフォルトは , (カンマ)です。Unicodeコード ポイントでも指定できます。詳細については、 unicode ディレクティブを参照してください。

quote : 1文字 : char

クォート文字を表す1文字[3] で、区切り文字またはクォート文字自身を含む要素を囲むために使われます。デフォルトは " (クォート)です。Unicodeコード ポイントでも指定できます。詳細については、 unicode ディレクティブを参照してください。

keepspace : フラグ : flag

区切り文字の直後の空白をそのまま残します。デフォルでは、このような空白を無視します。

escape : 1文字 : char

エスケープ文字を表す1文字[3] で、区切り文字またはクォート文字をエスケープするために使われます。Unicodeコード ポイントでも指定できます。詳細については、 unicode ディレクティブを参照してください。クォートされていないところに区切り文字を使いたい場合や、クォート文字をフィールド内で使いたい時に使います。デフォルトでは、"He said, ""Hi!""" のようにその文字を2重にします。

他に共通のオプションとして :class::name: があります。

リストテーブル

Directive Type:"list-table"
Doctree Element:
 table
Directive Arguments:
 

1つ、省略可(テーブルタイトル)

Directive Options:
 

指定可能、以下を参照.

Directive Content:
 

2階層の箇条書きリスト

(Docutils 0.3.8で追加。これは、初期実装です。今後、 将来のアイディア が実装されるかもしれません。)

"list-table"ディレクティブは均一な2階層の箇条書きリストからテーブルを作成します。「均一」とは、各サブリスト(2階層目のリスト)が同じ項目数でなければならないことを意味します。

例:

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

以下のオプションを使用出来ます:

widths : 数値 [数値...] : integer [integer...]

コンマまたはスペースで区切られた、相対列幅のリスト。デフォルトでは幅の等しい列 (100%/#columns)です。

header-rows : 数値 : integer

テーブルのヘッダーとして使用する行数です。デフォルトは0です。

stub-columns : 数値 : integer

スタブ(行の左のタイトル列)として使用するテーブル列の数です。デフォルトは0です。

他に共通のオプションとして :class::name: があります。

Document Parts

目次

Directive Type:"contents"
Doctree Elements:
 pending, topic
Directive Arguments:
 

1つ、省略可: タイトル

Directive Options:
 

指定可能

Directive Content:
 None.

"contents" ディレクティブは目次(Table of Contents: TOC)を topic エレメントとして生成します。トピックとその派生である目次は、セクション内のどこに書いてもかまいません。本文エレメントやトピックは目次を含められません。

これは、ディレクティブの最もシンプルな使い方です:

.. contents::

タイトルのデフォルト値は、言語によって異なるテキストが使用されます。英語の既定のタイトル テキストは、 "Contents" です。

明示的なタイトルを指定できます:

.. contents:: Table of Contents

タイトルは行をまたがっても書けますが、お勧めしません。

.. contents:: Here's a very long Table of
   Contents title

フィールド リストを使用してディレクティブのオプションが指定できます:

.. contents:: Table of Contents
   :depth: 2

タイトルを指定しない場合、オプションとなるフィールド リストをディレクティブと同じ行ではじめることもできます:

.. contents:: :depth: 2

以下のオプションを使用出来ます:

depth : 数値 : integer

目次に記載するセクションレベルの数。デフォルトは無制限です。

local : flag (empty)

ディレクティブがあるセクションの内側の要素だけを目次の対象として生成します。タイトルを指定していない場合、タイトルが付きません。

backlinks : "entry" か "top" か "none" : "entry" or "top" or "none"

セクションヘッダーからのリンクを生成します。"entry"で目次項目へのバックリンク、"top"で目次自体、"none"でバックリンクを生成しません。

class : text

topicエレメントの "classes" 属性を指定します。 class ディレクティブを参照してください。

Automatic Section Numbering

Directive Type:"sectnum" or "section-numbering" (synonyms)
Doctree Elements:
 pending, generated
Directive Arguments:
 None.
Directive Options:
 

指定可能

Directive Content:
 None.
Configuration Setting:
 sectnum_xform

The "sectnum" (or "section-numbering") directive automatically numbers sections and subsections in a document (if not disabled by the --no-section-numbering command line option or the sectnum_xform configuration setting).

Section numbers are of the "multiple enumeration" form, where each level has a number, separated by periods. For example, the title of section 1, subsection 2, subsubsection 3 would have "1.2.3" prefixed.

The "sectnum" directive does its work in two passes: the initial parse and a transform. During the initial parse, a "pending" element is generated which acts as a placeholder, storing any options internally. At a later stage in the processing, the "pending" element triggers a transform, which adds section numbers to titles. Section numbers are enclosed in a "generated" element, and titles have their "auto" attribute set to "1".

以下のオプションを使用出来ます:

depth : 数値 : integer
The number of section levels that are numbered by this directive. The default is unlimited depth.
prefix : string
An arbitrary string that is prefixed to the automatically generated section numbers. It may be something like "3.2.", which will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that any separating punctuation (in the example, a period, ".") must be explicitly provided. The default is no prefix.
suffix : string
An arbitrary string that is appended to the automatically generated section numbers. The default is no suffix.
start : integer
The value that will be used for the first section number. Combined with prefix, this may be used to force the right numbering for a document split over several source files. The default is 1.

References

Target Footnotes

Directive Type:"target-notes"
Doctree Elements:
 pending, footnote, footnote_reference
Directive Arguments:
 None.
Directive Options:
 :class:, :name:
Directive Options:
 

指定可能

Directive Content:
 None.

The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote references after each reference. For every explicit target (of the form, .. _target name: URL) in the text, a footnote will be generated containing the visible URL as content.

脚注

NOT IMPLEMENTED YET

Directive Type:"footnotes"
Doctree Elements:
 pending, topic
Directive Arguments:
 None?
Directive Options:
 Possible?
Directive Content:
 None.

@@@

引用

NOT IMPLEMENTED YET

Directive Type:"citations"
Doctree Elements:
 pending, topic
Directive Arguments:
 None?
Directive Options:
 Possible?
Directive Content:
 None.

@@@

HTML-Specific

Meta

Directive Type:"meta"
Doctree Element:
 meta (non-standard)
Directive Arguments:
 None.
Directive Options:
 None.
Directive Content:
 Must contain a flat field list.

The "meta" directive is used to specify HTML metadata stored in HTML META tags. "Metadata" is data about data, in this case data about web pages. Metadata is used to describe and classify web pages in the World Wide Web, in a form that is easy for search engines to extract and collate.

Within the directive block, a flat field list provides the syntax for metadata. The field name becomes the contents of the "name" attribute of the META tag, and the field body (interpreted as a single string without inline markup) becomes the contents of the "content" attribute. For example:

.. meta::
   :description: The reStructuredText plaintext markup language
   :keywords: plaintext, markup language

This would be converted to the following HTML:

<meta name="description"
    content="The reStructuredText plaintext markup language">
<meta name="keywords" content="plaintext, markup language">

Support for other META attributes ("http-equiv", "scheme", "lang", "dir") are provided through field arguments, which must be of the form "attr=value":

.. meta::
   :description lang=en: An amusing story
   :description lang=fr: Une histoire amusante

And their HTML equivalents:

<meta name="description" lang="en" content="An amusing story">
<meta name="description" lang="fr" content="Une histoire amusante">

Some META tags use an "http-equiv" attribute instead of the "name" attribute. To specify "http-equiv" META tags, simply omit the name:

.. meta::
   :http-equiv=Content-Type: text/html; charset=ISO-8859-1

HTML equivalent:

<meta http-equiv="Content-Type"
     content="text/html; charset=ISO-8859-1">

Imagemap

NOT IMPLEMENTED YET

Non-standard element: imagemap.

Directives for Substitution Definitions

The directives in this section may only be used in substitution definitions. They may not be used directly, in standalone context. The image directive may be used both in substitution definitions and in the standalone context.

Replacement Text

Directive Type:"replace"
Doctree Element:
 Text & inline elements
Directive Arguments:
 None.
Directive Options:
 None.
Directive Content:
 A single paragraph; may contain inline markup.

The "replace" directive is used to indicate replacement text for a substitution reference. It may be used within substitution definitions only. For example, this directive can be used to expand abbreviations:

.. |reST| replace:: reStructuredText

Yes, |reST| is a long word, so I can't blame anyone for wanting to
abbreviate it.

As reStructuredText doesn't support nested inline markup, the only way to create a reference with styled text is to use substitutions with the "replace" directive:

I recommend you try |Python|_.

.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/

Unicode Character Codes

Directive Type:"unicode"
Doctree Element:
 Text
Directive Arguments:
 One or more, required (Unicode character codes, optional text, and comments).
Directive Options:
 

指定可能

Directive Content:
 None.

The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions only.

The arguments, separated by spaces, can be:

  • character codes as
    • decimal numbers or
    • hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character entities, e.g. &#x1a2b;
  • text, which is used as-is.

Text following " .. " is a comment and is ignored. The spaces between the arguments are ignored and thus do not appear in the output. Hexadecimal codes are case-insensitive.

For example, the following text:

Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
all rights reserved.

.. |copy| unicode:: 0xA9 .. copyright sign
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
   .. with trademark sign
.. |---| unicode:: U+02014 .. em dash
   :trim:

results in:

Copyright © 2003, BogusMegaCorp™—all rights reserved.

以下のオプションを使用出来ます:

ltrim : flag
Whitespace to the left of the substitution reference is removed.
rtrim : flag
Whitespace to the right of the substitution reference is removed.
trim : flag
Equivalent to ltrim plus rtrim; whitespace on both sides of the substitution reference is removed.

Date

Directive Type:"date"
Doctree Element:
 Text
Directive Arguments:
 One, optional (date format).
Directive Options:
 None.
Directive Content:
 None.

The "date" directive generates the current local date and inserts it into the document as text. This directive may be used in substitution definitions only.

The optional directive content is interpreted as the desired date format, using the same codes as Python's time.strftime function. The default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also be used. Examples:

.. |date| date::
.. |time| date:: %H:%M

Today's date is |date|.

This document was generated on |date| at |time|.

Miscellaneous

Including an External Document Fragment

Directive Type:"include"
Doctree Elements:
 Depend on data being included (literal_block with code or literal option).
Directive Arguments:
 One, required (path to the file to include).
Directive Options:
 

指定可能

Directive Content:
 None.
Configuration Setting:
 file_insertion_enabled

警告

The "include" directive represents a potential security hole. It can be disabled with the "file_insertion_enabled" runtime setting.

The "include" directive reads a text file. The directive argument is the path to the file to be included, relative to the document containing the directive. Unless the options literal or code are given, the file is parsed in the current document's context at the point of the directive. For example:

This first example will be parsed at the document level, and can
thus contain any construct, including section headers.

.. include:: inclusion.txt

Back in the main document.

    This second example will be parsed in a block quote context.
    Therefore it may only contain body elements.  It may not
    contain section headers.

    .. include:: inclusion.txt

If an included document fragment contains section structure, the title adornments must match those of the master document.

Standard data files intended for inclusion in reStructuredText documents are distributed with the Docutils source code, located in the "docutils" package in the docutils/parsers/rst/include directory. To access these files, use the special syntax for standard "include" data files, angle brackets around the file name:

.. include:: <isonum.txt>

The current set of standard "include" data files consists of sets of substitution definitions. See reStructuredText Standard Definition Files for details.

以下のオプションを使用出来ます:

start-line : integer
Only the content starting from this line will be included. (As usual in Python, the first line has index 0 and negative values count from the end.)
end-line : integer
Only the content up to (but excluding) this line will be included.
start-after : text to find in the external data file
Only the content after the first occurrence of the specified text will be included.
end-before : text to find in the external data file
Only the content before the first occurrence of the specified text (but after any after text) will be included.
literal : flag (empty)
The entire included text is inserted into the document as a single literal block.
code : formal language (optional)
The argument and the content of the included file are passed to the code_ directive (useful for program listings). (New in Docutils 0.9)
number-lines : [開始行番号] : [start line number]
Precede every code line with a line number. The optional argument is the number of the first line (defaut 1). Works only with code or literal. (New in Docutils 0.9)
encoding : テキストのエンコーディング名 : name of text encoding
The text encoding of the external data file. Defaults to the document's input_encoding.
tab-width : integer
Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the tab_width configuration setting.

With code or literal the common options :class: and :name: are recognized as well.

Combining start/end-line and start-after/end-before is possible. The text markers will be searched in the specified lines (further limiting the included content).

Raw Data Pass-Through

Directive Type:"raw"
Doctree Element:
 raw
Directive Arguments:
 One or more, required (output format types).
Directive Options:
 

指定可能

Directive Content:
 Stored verbatim, uninterpreted. None (empty) if a "file" or "url" option given.
Configuration Setting:
 raw_enabled

警告

The "raw" directive represents a potential security hole. It can be disabled with the "raw_enabled" or "file_insertion_enabled" runtime settings.

ご用心

The "raw" directive is a stop-gap measure allowing the author to bypass reStructuredText's markup. It is a "power-user" feature that should not be overused or abused. The use of "raw" ties documents to specific output formats and makes them less portable.

If you often need to use the "raw" directive or a "raw"-derived interpreted text role, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText. Please describe your situation in a message to the Docutils-users mailing list.

The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The names of the output formats are given in the directive arguments. The interpretation of the raw data is up to the Writer. A Writer may ignore any raw output not matching its format.

For example, the following input would be passed untouched by an HTML Writer:

.. raw:: html

   <hr width=50 size=10>

A LaTeX Writer could insert the following raw content into its output stream:

.. raw:: latex

   \setlength{\parindent}{0pt}

Raw data can also be read from an external file, specified in a directive option. In this case, the content block must be empty. For example:

.. raw:: html
   :file: inclusion.html

Inline equivalents of the "raw" directive can be defined via custom interpreted text roles derived from the "raw" role.

以下のオプションを使用出来ます:

file : 文字列(改行は取り除かれます) : string (newlines removed)
The local filesystem path of a raw data file to be included.
url : 文字列 (空白は取り除かれます) : string (whitespace removed)
An Internet URL reference to a raw data file to be included.
encoding : テキストのエンコーディング名 : name of text encoding
The text encoding of the external raw data (file or URL). Defaults to the document's encoding (if specified).

Class

Directive Type:"class"
Doctree Element:
 pending
Directive Arguments:
 One or more, required (class names / attribute values).
Directive Options:
 None.
Directive Content:
 Optional. If present, it is interpreted as body elements.

The "class" directive sets the "classes" attribute value on its content or on the first immediately following [4] non-comment element [5]. For details of the "classes" attribute, see the classes entry in The Docutils Document Tree.

The directive argument consists of one or more space-separated class names. The names are transformed to conform to the regular expression [a-z](-?[a-z0-9]+)* by converting

  • alphabetic characters to lowercase,
  • accented characters to the base character,
  • non-alphanumeric characters to hyphens,
  • consecutive hyphens into one hyphen.

For example "Rot-Gelb.Blau Grün:+2008" becomes "rot-gelb-blau grun-2008". (For the rationale, see below.)

例:

.. class:: special

This is a "special" paragraph.

.. class:: exceptional remarkable

An Exceptional Section
======================

This is an ordinary paragraph.

.. class:: multiple

   First paragraph.

   Second paragraph.

The text above is parsed and transformed into this doctree fragment:

<paragraph classes="special">
    This is a "special" paragraph.
<section classes="exceptional remarkable">
    <title>
        An Exceptional Section
    <paragraph>
        This is an ordinary paragraph.
    <paragraph classes="multiple">
        First paragraph.
    <paragraph classes="multiple">
        Second paragraph.
[4]

This is also true, if the class directive is "nested" at the end of an indented text block, for example:

.. note:: the class values set in this directive-block do not apply to
   the note but the next paragraph.

   .. class:: special

This is a paragraph with class value "special".

This allows the "classification" of individual list items (except the first, as a preceding class directive applies to the list as a whole):

* bullet list

  .. class:: classy item

* second item, with class argument
[5]

To set a "classes" attribute value on a block quote, the "class" directive must be followed by an empty comment:

.. class:: highlights
..

    Block quote text.

Without the empty comment, the indented text would be interpreted as the "class" directive's content, and the classes would be applied to each element (paragraph, in this case) individually, instead of to the block quote as a whole.

Rationale for "classes" Attribute Value Conversion

Docutils identifiers are converted to conform to the regular expression [a-z](-?[a-z0-9]+)*. For HTML + CSS compatibility, identifiers (the "classes" and "id" attributes) should have no underscores, colons, or periods. Hyphens may be used.

  • The HTML 4.01 spec defines identifiers based on SGML tokens:

    ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

  • The CSS1 spec defines identifiers based on the "name" token ("flex" tokenizer notation below; "latin1" and "escape" 8-bit characters have been replaced with XML entities):

    unicode     \\[0-9a-f]{1,4}
    latin1      [&iexcl;-&yuml;]
    escape      {unicode}|\\[ -~&iexcl;-&yuml;]
    nmchar      [-A-Za-z0-9]|{latin1}|{escape}
    name        {nmchar}+
    

The CSS rule does not include underscores ("_"), colons (":"), or periods ("."), therefore "classes" and "id" attributes should not contain these characters. Combined with HTML's requirements (the first character must be a letter; no "unicode", "latin1", or "escape" characters), this results in the regular expression [A-Za-z][-A-Za-z0-9]*. Docutils adds a normalisation by downcasing and merge of consecutive hyphens.

Custom Interpreted Text Roles

Directive Type:"role"
Doctree Element:
 None; affects subsequent parsing.
Directive Arguments:
 Two; one required (new role name), one optional (base role name, in parentheses).
Directive Options:
 Possible (depends on base role).
Directive Content:
 depends on base role.

(New in Docutils 0.3.2)

The "role" directive dynamically creates a custom interpreted text role and registers it with the parser. This means that after declaring a role like this:

.. role:: custom

the document may use the new "custom" role:

An example of using :custom:`interpreted text`

This will be parsed into the following document tree fragment:

<paragraph>
    An example of using
    <inline classes="custom">
        interpreted text

The role must be declared in a document before it can be used.

The new role may be based on an existing role, specified as a second argument in parentheses (whitespace optional):

.. role:: custom(emphasis)

:custom:`text`

The parsed result is as follows:

<paragraph>
    <emphasis classes="custom">
        text

A special case is the "raw" role: derived roles enable inline raw data pass-through, e.g.:

.. role:: raw-role(raw)
   :format: html latex

:raw-role:`raw text`

If no base role is explicitly specified, a generic custom role is automatically used. Subsequent interpreted text will produce an "inline" element with a "classes" attribute, as in the first example above.

With most roles, the ":class:" option can be used to set a "classes" attribute that is different from the role name. For example:

.. role:: custom
   :class: special

:custom:`interpreted text`

This is the parsed result:

<paragraph>
    <inline classes="special">
        interpreted text

The following option is recognized by the "role" directive for most base roles:

class : text
Set the "classes" attribute value on the element produced (inline, or element associated with a base class) when the custom interpreted text role is used. If no directive options are specified, a "class" option with the directive argument (role name) as the value is implied. See the class directive above.

Specific base roles may support other options and/or directive content. See the reStructuredText Interpreted Text Roles document for details.

Setting the Default Interpreted Text Role

Directive Type:"default-role"
Doctree Element:
 None; affects subsequent parsing.
Directive Arguments:
 One, optional (new default role name).
Directive Options:
 None.
Directive Content:
 None.

(Docutils 0.3.10から追加)

The "default-role" directive sets the default interpreted text role, the role that is used for interpreted text without an explicit role. For example, after setting the default role like this:

.. default-role:: subscript

any subsequent use of implicit-role interpreted text in the document will use the "subscript" role:

An example of a `default` role.

This will be parsed into the following document tree fragment:

<paragraph>
    An example of a
    <subscript>
        default
     role.

Custom roles may be used (see the "role" directive above), but it must have been declared in a document before it can be set as the default role. See the reStructuredText Interpreted Text Roles document for details of built-in roles.

The directive may be used without an argument to restore the initial default interpreted text role, which is application-dependent. The initial default interpreted text role of the standard reStructuredText parser is "title-reference".

Metadata Document Title

Directive Type:"title"
Doctree Element:
 None.
Directive Arguments:
 1, required (the title text).
Directive Options:
 None.
Directive Content:
 None.

The "title" directive specifies the document title as metadata, which does not become part of the document body. It overrides a document-supplied title. For example, in HTML output the metadata document title appears in the title bar of the browser window.

Restructuredtext-Test-Directive

Directive Type:"restructuredtext-test-directive"
Doctree Element:
 system_warning
Directive Arguments:
 None.
Directive Options:
 None.
Directive Content:
 Interpreted as a literal block.

This directive is provided for test purposes only. (Nobody is expected to type in a name that long!) It is converted into a level-1 (info) system message showing the directive data, possibly followed by a literal block containing the rest of the directive block.

Common Options

Most of the directives that generate doctree elements support the following options:

:class: : text
Set a "classes" attribute value on the doctree element generated by the directive. See also the class directive.
:name: : text

Add text to the "names" attribute of the doctree element generated by the directive. This allows hyperlink references to the element using text as reference name.

Specifying the name option of a directive, e.g.,

.. image:: bild.png
   :name: my picture

is a concise syntax alternative to preceding it with a hyperlink target

.. _my picture:

.. image:: bild.png

New in Docutils 0.8.