reStructuredText入門¶
警告
この記事は古い為 easy_install の使用等、現在では非推奨の説明があります。インストール周りについては Windowsへのインストールの手順を参照してください。
reStructuredTextはreSTとも呼ばれます。 (http://docutils.sourceforge.net/rst.html (英語) を参照してください。) reSTは、プレーンテキストを使ったマークアップ言語で、パッケージのドキュメントを作成する際に、Pythonのコミュニティ内で広く使用されています。reSTの優れている点は、ソースのテキストの状態でもそのまま読むことができるという点です。LaTeXのように、マークアップの文法のせいで読みにくくなるということはありません。
以下のテキストは、reST形式のドキュメントのサンプルです。
========
タイトル
========
セクション 1
============
この **単語** は強調されます。
セクション 2
============
サブセクション
::::::::::::::
テキスト。
reSTはdocutilsパッケージに含まれています。docutilsには、reSTのファイルをHTML, LaTeX, XMLなどの様々なフォーマットに変換するスクリプトが含まれます。S5という、Eric Meyerのスライドショーのシステム (http://meyerweb.com/eric/tools/s5/ を参照)のためのフォーマットにも変換することができます。
ドキュメント作成者は内容にフォーカスし、必要に応じて、その後にどのようにレンダリングされるのかを決めることができます。Python自身のドキュメントもreSTで書かれています。このファイルは後でHTMLに変換され http://docs.python.org のウェブサイトが構築されています。PDFなどの他のフォーマットにも変換されています。
reSTのテキストを書き始めるにあたって、まず知るべき最小の項目は次の通りです:
セクション構造
リスト
インラインマークアップ
リテラルブロック
リンク
このセクションでは文法を駆け足で説明しています。http://docutils.sourceforge.net/docs/user/rst/quickref.html にあるクリックリファレンスを見ると、より多くの情報を得ることができます。このウェブサイトは、reSTを仕事で使い始める際にはとても参考になるでしょう。
reStructuredTextをインストールするために、docutilsをインストールします。
$ easy_install docutils
インストールが完了すると、rst2から始まるスクリプトがインストールされます。これらのスクリプトを使用すると、reSTをさまざまな形式にレンダリングすることができます。
例えば、rst2htmlスクリプトを使うと、与えられたreSTファイルからHTMLファイルを出力することができます:
$ more text.txt
タイトル
========
内容。
$ rst2html.py text.txt > text.html
$ more text.html
<?xml version="1.0" encoding="utf-8" ?>
...
<html ...>
<head>
...
</head>
<body>
<div class="document" id="title">
<h1 class="title">タイトル</h1>
<p>内容。</p>
</div>
</body>
</html>
セクション構造¶
ドキュメントのタイトルと、セクションは、アルファベットでも数字でもない文字を使ってアンダーラインにすることで表現されます。オーバーラインとアンダーラインの両方を使用することもできます。タイトルを表現する時には上下に付け、セクション名に対してはアンダーラインのみ、というのが一般的に使用されるプラクティスです。
セクションタイトルのアンダーラインに使用される記号として頻繁に使用されるのは、=, -, _, :, #, +, ^, があります。
セクションタイトルに使用する記号の種類を変えていくことで、セクションの深さのレベルが変わっていきます。使用する記号の種類はドキュメント内で一貫している必要があります。
サンプル:
========
タイトル
========
セクション 1
============
xxx
セクション 2
============
xxx
サブセクション C
----------------
xxx
このファイルをHTML出力すると、上記の図で示したような見た目になります。
リスト¶
reSTでは、箇条書き、列挙型、定義リストを使用することができます。自動採番機能も使用できます:
箇条書きリスト:
- 一番
- 二番
- 三番
列挙型リスト
1. 一番
2. 二番
#. #を前に付けると、自動で番号が割り振られます
定義リスト
一
一は数字です。
二
二も数字です。
インラインマークアップ¶
次のようなインラインマークアップを使用すると、テキストのスタイルを変えることができます:
*強調*: イタリック
**強い強調**: 太字
``インラインリテラル``: インラインフォーマット済みテキスト
`リンク付きのテキスト`_: 同じ名前のものがドキュメント内にあれば、
ハイパーリンクに置き換えられます(詳しくはリンクのセクションで説明します).
リテラルブロック¶
コードサンプルを表現したい場合には、リテラルブロックを使用することができます。コロンを2つ( :: )書くとブロックをあらわす記号になります。インデントされたパラグラフがブロックとして扱われます:
コードサンプルです
::
>>> 1 + 1
2
ここからテキストに戻ります。
注釈
:: 記号の後と、ブロックの後には空行を入れるのを忘れないようにしてください。入れ忘れるとレンダリングされなくなります。
'::' はテキスト行にも書くことが可能です。テキスト行の末尾に書くことで、「：」１つがレンダリングされます。
コードのサンプル::
>>> 1 + 1
2
テキストの続き。
もしもコロンをレンダリングしたくない場合には、行末の"サンプル"の文字と、 :: の記号の間にスペースを入れると、 :: はブロックの始まりとして解釈されますが、レンダリングされません。
リンク¶
もしも、ソースのテキスト内にドット二つから始まる特殊な外部参照リンク情報の行があると、インラインマークアップのリンク付きのテキストは、外部参照リンクに置き換えられます。
`Plone CMS`_ を試してみてください。これはすばらしいですよ！ Zope_ 上に作られています。
.. _`Plone CMS`: http://plone.org
.. _Zope: http://zope.org
一般的には、外部参照リンクのグループはドキュメントの末尾にまとめて置かれます。リンクされるテキストにスペースが含まれる場合や、日本語などを使用する場合には、 ` (バッククオート) 文字で囲むようにしてください。
内部リンクは、テキストの中にマーカーを追加することでも実現することができます:
これはコード例です。
.. _example:
::
>>> 1 + 1
2
テキストの続き。コード例に戻る場合はこちら example_
セクションはターゲットとして使用することもできます。日本語やスペースを含む場合にはシングルクオートでくくります。
========
タイトル
========
セクション 1
============
xxx
サブセクション A
-----------------
xxx
サブセクション B
-----------------
-> `サブセクション A`_ に戻る
セクション 2
============