原文: | reStructuredText Directives(rev.7747) |
---|---|
原著者: | David Goodger |
著者: | helloaworld.com |
連絡先: | http://helloaworld.com |
Revision: | 0.0 |
Date: | 2014/11/1 |
Copyright: | クリエイティブコモンズ 表示-非営利-継承 |
目次
“image”と”figure”、二つのディレクティブがあります。
Directive Type: | “image” |
---|---|
Directive Arguments: | |
画像のURIが一つ必須 |
|
Directive Options: | |
|
|
Directive Content: | |
無し |
コードの例:
.. image:: picture.jpeg
:height: 100px
:width: 200 px
:scale: 50 %
:alt: alternate text
:align: right
Makes the image into a hyperlink reference ("clickable"). The
option argument may be a URI (relative or absolute), or a
`reference name`_ with underscore suffix (e.g. ```a name`_``).
Directive Type: | “figure” |
---|---|
Directive Arguments: | |
画像のURIが一つ必須 |
|
Directive Options: | |
|
|
Directive Content: | |
任意のキャプション |
+---------------------------+
| figure |
| |
|<------ figwidth --------->|
| |
| +---------------------+ |
| | image | |
| | | |
| |<--- width --------->| |
| +---------------------+ |
| |
|The figure's caption should|
|wrap at this width. |
+---------------------------+
Directive Type: | “topic” |
---|---|
Directive Arguments: | |
タイトルとして一つ必要 | |
Directive Options: | |
共通オプション | |
Directive Content: | |
トピックの本文として解釈されます |
Topicは、文章を罫線で囲むことが出来ます。 タイトルを設定することが出来る特徴があります。
サンプル
トピックのタイトル
トピックの本文が ここに記載されます。
コード:
.. topic:: トピックのタイトル
トピックの本文が
ここに記載されます。
Directive Type: | “sidebar” |
---|---|
Directive Arguments: | |
タイトルとして一つ必要 |
|
Directive Options: | |
|
|
Directive Content: | |
本文として解釈されます。 |
サンプル
コード:
.. sidebar:: 再度バーのタイトル
:subtitle: サブタイトル
ここが本文です。
| この部分はこのように表示されます。
| 折り重なります。
|
|
|
|
このディレクティブは廃止予定のため、本ドキュメントでは省略します。 行ブロックを利用してください。 行ブロックは、行頭に”|”を配置する構文です。
Directive Type: | “parsed-literal” |
---|---|
Directive Arguments: | |
無し | |
Directive Options: | |
共通オプション | |
Directive Content: | |
本文 |
リテラルブロックと異なって、インラインマークアップが解釈されます。
サンプル
インラインマークアップが 解釈されます。
.. parsed-literal::
インラインマークアップが **解釈されます。**
Directive Type: | “code” |
---|---|
Directive Arguments: | |
任意で、言語を指定できます。 |
|
Directive Options: | |
|
|
Directive Content: | |
本文 |
コードの言語が解釈されてハイライトなどが行われます。
サンプル
5 def my_function(): 6 "just a test" 7 print 8/2
コード:
.. code:: python
:number-lines: 5
def my_function():
"just a test"
print 8/2
ヒント
sphinxでもcode-blockディレクティブ等拡張が行われています。sphinxでは、code-blockを利用した方が良いでしょう。
Directive Type: | “math” |
---|---|
Directive Arguments: | |
任意で、一つの見せ掛けの本文を指定可能。 | |
Directive Options: | |
共通オプション | |
Directive Content: | |
本文。数式などが解釈されます。 |
latex形式の数式構文が使用できます。 htmlに変換するには、その他設定が必要です。
ヒント
sphinxの拡張機能を利用できます。sphinx利用の場合は、sphinxのドキュメントを参照してください。
コード:
.. math::
α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
Directive Type: | “rubric” |
---|---|
Doctree Element: | |
rubric | |
Directive Arguments: | |
1, required (rubric text). | |
Directive Options: | |
共通オプション | |
Directive Content: | |
None. |
目次等に影響のない、見出しの様なものを作れます。
サンプル
たたdふぁsjklfだsjk
.. rubric:: たたdふぁsjklfだsjk
Directive Type: | “epigraph” |
---|---|
Directive Arguments: | |
無し | |
Directive Options: | |
無し | |
Directive Content: | |
本文 |
題辞を記載できます。
サンプル
No matter where you go, there you are.
—Buckaroo Banzai
.. epigraph::
No matter where you go, there you are.
-- Buckaroo Banzai
Directive Type: | “highlights” |
---|---|
Directive Arguments: | |
無し | |
Directive Options: | |
無し | |
Directive Content: | |
本文 |
epigraphと類似した動作になります。
Directive Type: | “pull-quote” |
---|---|
Directive Arguments: | |
無し | |
Directive Options: | |
無し | |
Directive Content: | |
本文 |
epigraphと類似した動作になります。
Directive Type: | “compound” |
---|---|
Directive Arguments: | |
None. | |
Directive Options: | |
共通オプション | |
Directive Content: | |
Interpreted as body elements. |
同じレベルの段落で、ディレクティブオプションの共通オプションを適応できます。 htmlでは問題が起こる可能性があるので、後述のContainerを使ってください。
Directive Type: | “container” |
---|---|
Directive Arguments: | |
任意でclass namesを指定可能 | |
Directive Options: | |
name: | |
Directive Content: | |
本文 |
classesを引数として受け取れます。 同じレベルの段落で、共通オプションのclassesやnameが設定できます。、
コード例:
.. container:: custom
This paragraph might be rendered in a custom way.
表は、reStructuredText構文が提供しています。ただ、タイトルをつけたり、csvデータをサポートできません。これをディレクティブでサポートできます。
Directive Type: | “table” |
---|---|
Directive Arguments: | |
任意で、表のタイトル | |
Directive Options: | |
共通オプション | |
Directive Content: | |
reStructuredText形式の表 |
サンプル
A | not A |
---|---|
False | True |
True | False |
コード:
.. table:: Truth table for "not"
===== =====
A not A
===== =====
False True
True False
===== =====
Directive Type: | “csv-table” |
---|---|
Directive Arguments: | |
任意で、表のタイトルを指定可能。 |
|
Directive Options: | |
|
|
Directive Content: | |
csv形式の表 |
このディレクティブは、csv形式で表を記述できます。またcsvファイルをインポートして、表にすることも出来ます。
サンプル
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! |
コード:
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
:stub-columns: 2
"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-tableディレクティブは、fileとurlのオプションに潜在的なセキュリティーホールがあります。”file_insertion_enabled”のランタイム設定を無効化すれば、回避できます。
Directive Type: | “list-table” |
---|---|
Directive Arguments: | |
任意でテーブルのタイトル一つ。 |
|
Directive Options: | |
|
|
Directive Content: | |
二階層の箇条書きリスト |
二階層の箇条書きリストの、二階層目の項目数はそれぞれ等しい必要があります。
サンプル
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! |
コード:
.. 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!
Directive Type: | “contents” |
---|---|
Directive Arguments: | |
任意でタイトル一つ |
|
Directive Options: | |
|
|
Directive Content: | |
無し。 |
見出しを作成する
サンプル:
ここがタイトル
コード:
.. contents:: ここがタイトル
:depth: 2
:backlinks: none
Directive Type: | “sectnum” or “section-autonumbering” (synonyms) |
---|---|
Directive Arguments: | |
無し。 |
|
Directive Options: | |
|
|
Directive Content: | |
無し |
警告
sphinxでは、docutilsの本ディレクティブを使用しないように呼びかけられています。
Directive Type: | “meta” |
---|---|
Directive Arguments: | |
無し |
|
Directive Options: | |
原文には無しとありましたが、フィールドリストとして与えることの出来るタグを列挙します。
|
|
Directive Content: | |
単一階層のフィールドリストを含む必要があります。 |
metaディレクティブは、HTMLのメタタグ(<meta></meta>)内のメタデータを 記述するために使われます。サーチエンジンが抜粋や照合を 行い易くする形式で、メタデータでwebページを分類することができます。
コード例:
.. meta::
:description: The reStructuredText plaintext markup language
:keywords: plaintext, markup language
:description lang=en: An amusing story
:http-equiv=Content-Type: text/html; charset=ISO-8859-1
HTMLへの変換結果:
<meta name="description"
content="The reStructuredText plaintext markup language">
<meta name="keywords" content="plaintext, markup language">
<meta name="description" lang="en" content="An amusing story">
<meta http-equiv="Content-Type"
content="text/html; charset=ISO-8859-1">
本章のディレクティブは、置換を定義するために利用されます。 これらは、脈絡無く単独で、直に呼び出されないものがあります。 imageディレクティブのように、単独でも利用できるものもあります。
Directive Type: | “replace” |
---|---|
Directive Arguments: | |
無し。 | |
Directive Options: | |
無し。 | |
Directive Content: | |
インラインマークアップを含むことが出来る、単一の段落。 |
replaceディレクティブは、参照したものの置換を指示出来ます。 置換内容の定義しかできません。 例えば、略記や略称を展開するために利用できます。 また、ネストしたインラインマークアップはサポートされていません。 参照を行う唯一の方法は、置換対象の文字列を利用して行えます。
サンプルは以下
そらいけっ、 かえるの歌が聞こえてくるよ♪
コード:
そらいけっ、 |かえるの歌|
.. |かえるの歌| replace:: かえるの歌が聞こえてくるよ♪
.. _かえるの歌: http://kaerugakae.ru
Directive Type: | “unicode” |
---|---|
Directive Arguments: | |
一つ以上が必要。(unicodeの文字コード、任意の文字列、コメント) |
|
Directive Options: | |
|
|
Directive Content: | |
None. |
”..”以降はコメントとして無視されます。また、 スペースで区切られた引数は以下のように指定できます。
- 10進数
- 右記の文字に続けた16進数。 0x, x, \x, U+, u, \u
- xml形式の16進数表記。 ᨫ
サンプル:
Copyright© 2005, 桃太郎交通 ™ — all rights reserved.
コード:
|copyr| 2005, 桃太郎交通 |TM| |---| all rights reserved.
.. |copyr| unicode:: Copyright 0xA9 .. circle c
.. |TM| unicode:: U+2122
.. |---| unicode:: —
Directive Type: | “date” |
---|---|
Directive Arguments: | |
任意で一つ。(日付の形式) | |
Directive Options: | |
無し | |
Directive Content: | |
無し |
オプションとして与えることの出来るコードは、 Pythonのtime.strftime関数の形式です。 デフォルトは、“%Y-%m-%d” (ISO 8601 date)です。
サンプル:
この文章は 2014-11-07 …詳細には 2014年11月07日01時06分54秒 に作成されました。
コード:
.. |date| date::
.. |time| date:: %Y年%m月%d日%H時%M分%S秒
この文章は |date| …詳細には |time| に作成されました。
Directive Type: | “include” |
---|---|
Directive Arguments: | |
インクルードするファイルのパスが必須 |
|
Directive Options: | |
|
|
Directive Content: | |
無し |
|
Configuration Setting: | |
file_insertion_enabled |
警告
“include”ディレクティブは、潜在的なセキュリティーホールがあります。 これの無効化は、file_insertion_enabledのランタイム設定から行えます。
コード例:
インデント(クォート)されていないところで、本ディレクティブを実行すると、
セクションなどの構造を含むことが出来ます。
.. include:: some.txt
~~~~~~~
インデント(クォート)された場合は、セクション等の構造を含むことが出来ないかもしれません。
Directive Type: | “raw” |
---|---|
Directive Arguments: | |
outputする形式が一つ以上必要. |
|
Directive Options: | |
|
|
Directive Content: | |
バイパスされる文字列。ファイルパス若しくは、URLが指定されれば無し。 |
|
Configuration Setting: | |
raw_enabled |
警告
“raw”ディレクティブは、潜在的なセキュリティーホールがあります。 これの無効化は、raw_enabled若しくはfile_insertion_enabledのランタイム設定から行えます。
ご用心
この”raw”ディレクティブは、著者にreStructuredTextのマークアップを バイパスするための応急処置です。これはパワーユーザー用の機能で 乱用されるべきではありません。ドキュメントの出力フォーマットに制限が生まれ、 移植性が下がります。
“raw”ディレクティブや”raw”で生成されたテキストを度々使用する必要があれば、 それは乱用かreStructuredTextの機能上の欠陥です。 Docutils-usersのメーリングリストまで連絡ください。
コード:
.. raw:: html
<hr width=50 size=10>
.. raw:: latex
\setlength{\parindent}{0pt}
.. raw:: html
:file: inclusion.html
Directive Type: | “class” |
---|---|
Directive Arguments: | |
クラスの名前若しくは属性の値が一つ以上必要 | |
Directive Options: | |
無し | |
Directive Content: | |
任意。もし存在すれば、ボディ要素として解釈されます。 |
ヒント
sphinxでは、reStructuredTextのclassディレクティブがrst-classへと再定義されています。本ドキュメントは、sphinxで記述されているため、実例やサンプルではrst-classを利用します。
ディレクティブの引数は、一つ以上の半角スペースで区切られたクラス名です。クラス名は正規表現で、”[a-z](-?[a-z0-9]+)*”に合致する名前へと変換されます。要点は下記。
- アルファベットは、小文字へ
- アクセントされた文字は、基本文字へ(通常の日本語環境では、関係ないでしょう)
- 非英数字の文字は、ハイフンへ
- 連続したハイフンは、一つのハイフンへ
以下動作例。
ここは、”special”の段落です。
ここは、”special”の段落ではありません。
ここまでが動作例
以下はhtmlのソース:
<p class="special">ここは、”special”の段落です。</p>
<p>ここは、”special”の段落ではありません。</p>
<div class="exceptional remarkable section" id="exceptional-remakable">
<h4><a class="toc-backref" href="#id71">これはexceptional remakableクラスのセクションです(本章は動作例です。)</a>
<a class="headerlink" href="#exceptional-remakable" title="Permalink to this headline">¶</a></h4>
<p>普通の段落。</p>
<p class="multiple">“multiple”な段落。</p>
<p class="multiple">ここも”multiple”な段落。</p>
</div>
以下は、コード:
.. rst-class:: special
ここは、"special"の段落です。
ここは、"special"の段落ではありません。
.. rst-class:: exceptional remarkable
これはexceptional remakableクラスのセクションです(本章は動作例です。)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
普通の段落。
.. rst-class:: multiple
"multiple"な段落。
ここも"multiple"な段落。
以下のように、”class”ディレクティブに続いて空のコメントをつけると、 <backquote>タグに対して、クラスが適応されます。空のコメントをつけない場合は、それぞれの要素(<p>タグで設定される)に対してclassが適応されます。
コード例:
.. rst-class:: highlights
..
Directive Type: | “role” |
---|---|
Directive Arguments: | |
新しいロール名一つが必須で、基本ロール名が任意で一つ。 | |
Directive Options: | |
可能。但し、基本ロールに依存します。 | |
Directive Content: | |
基本ロールに依存 |
“role”ディレクティブは、解釈が行われるテキストロールを新しく定義して、パーサー(構文解析器)に登録できます。これは、後付けで新しいロールを定義できるということです。
ヒント
基本ロールについての詳しい記述は、”reStructuredText Interpreted Text Roles”で行われています。
コード例1:
.. role:: raw-role(raw)
:format: html latex
:raw-role:`raw text`
コード例2:
.. role:: custom
:class: special
:custom:`interpreted text`
Directive Type: | “default-role” |
---|---|
Directive Arguments: | |
任意で一つ。(新しいデフォルトロール名). | |
Directive Options: | |
無し。 | |
Directive Content: | |
無し。 |
“default-role”ディレクティブは、デフォルトのテキストロールをセットします。 ロールが指示されていないテキストに適応されます。
以下のように設定が行えます:
.. default-role:: subscript
後に続けて、暗黙のロールとして解釈されるテキストを利用すると、 “subscript”ロールが使用されます。:
An example of a `default` role.
組み込まれたロールの詳細については”reStructuredText Interpreted Text Roles” を参照して下さい。このディレクティブは、アプリケーション環境に依存する 初期設定されたデフォルトロールの引数を復元することなく、利用してしまうことがあります。 reStrucuteredTextの標準の初期設定デフォルトロールは、”title-reference”です。
Directive Type: | “title” |
---|---|
Doctree Element: | |
無し。 | |
Directive Arguments: | |
タイトルの文字列が一つ必須(string) | |
Directive Options: | |
無し。 | |
Directive Content: | |
無し。 |
“title”ディレクティブは、メタデータとしてのドキュメントタイトルを明記できます。 これは、ドキュメントが供給するタイトルを上書きします。 ここで指定したタイトルは、例えばhtmlでは、ブラウザウィンドウのタイトルバー等に表示されます。
Directive Type: | “restructuredtext-test-directive” |
---|---|
Directive Arguments: | |
無し。 | |
Directive Options: | |
無し。 | |
Directive Content: | |
リテラルブロックとして解釈されるもの。 |
このディレクティブはテスト利用のものです。
これは、ディレクティブデータを表示するlevel-1(info)システムメッセージへと変換される。 恐らく、続けてディレクティブブロックの残りの部分を含むリテラルブロックが続く。