reStructuredText入門¶
このセクションは、reStructuredText(reST)の考え方や文法についての短いイントロダクションです。Sphinxユーザがドキュメントを作成するために十分な情報を提供します。reSTはシンプルに設計された、控えめなマークアップ言語ですので、理解するのにそれほど時間はかからないでしょう。
参考
本家 reStructuredTextユーザドキュメント このドキュメント中の参照リンクは、reSTのリファレンスの個々の要素の説明にリンクしています。
段落(パラグラフ)¶
段落(ref)はreSTドキュメントにおける、もっとも基本的な要素です。段落は1行以上の空行で区切られた、シンプルなテキストの固まりです。 Pythonにおいてインデントが重要な意味を持つのと同様、reSTでもインデントは重要です。同じ段落のすべての行は、インデントを同じ高さにそろえて、左揃えにしなければなりません。
インラインマークアップ¶
標準のreSTインラインマークアップは極めてシンプルです。
アスタリスク1つ:
*テキスト*強調( イタリック )アスタリスク2つ:
**テキスト**強い強調( 太文字 )バッククオート:
``テキスト``コードサンプル(固定長)
もしも、アスタリスクかバッククオートがテキスト中に使用する場合は、インラインマークアップの区切り文字と間違ってしまうことがあります。そのような場合には、バックスラッシュ(訳注:日本語フォントだと円記号)を使ってエスケープしてください。
このマークアップにはいくつかの制限があります。
ネストすることはできません
中のテキストの最初、もしくは最後にスペースを入れることもできません。
* text*と書くことはできません周囲のテキストとは、テキスト以外の文字(スペース、カッコなど)で区切る必要があります。もしも空白を空けずに、続けて表記したい場合には、
thisis\ *one*\ wordと、バックスラッシュでエスケープしたテキスト(スペースは表示されません)を使用してください。
これらの制限は、docutilsの将来のバージョンでも残るでしょう。
reSTには、”解釈済みテキストロール”というものが許されています。これは、 :ロール名:`解釈済みテキスト` という文法になります。これは、囲まれているテキストは特別な方法で解釈させることができる、というものです。Sphinxはこれをつかって、意味のマークアップと、識別子のマークアップを行っています。これに関しては別のセクションで説明します。
標準のreSTは次のようなロールを提供しています:
emphasis –
*emphasis*の代替表現strong –
**strong**の代替表現literal –
``literal``の代替表現subscript – 下付き文字
superscript – 上付き文字
title-reference – 書籍、定期刊行物などのタイトル
Sphinxによって追加されたロールに関しては インラインマークアップ を参照してください。
リストと引用のようなブロック¶
リストを表現するマークアップ (ref) はほぼ結果の見た目通りです。パラグラフの最初をアスタリスクで開始して、適切にインデントをしてやるだけです。ナンバー付きのリストも同様です。 # を使うことで、ナンバリングを自動で行うこともできます:
* This is a bulleted list.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
ネストされたリストも使用できますが、親のリストとは空白行で区切る必要があります:
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
定義リスト(ref)は以下のようにして作成します:
term (up to a line of text)
Definition of the term, which must be indented
and can even consist of multiple paragraphs
next term
Description.
用語のテキストは複数行書くことができないことに注意してください。
引用パラグラフ(ref)は周囲のパラグラフよりもインデントすることで作成できます。
ラインブロック(ref)を利用すると、改行状態をそのまま維持したまま出力できます:
| These lines are
| broken exactly like in
| the source file.
次のような特別なブロックも利用できます:
ソースコード¶
リテラルコードブロック(ref)は、前の段落の行末を特別な記号 :: にすることで開始できます。リテラルコードブロックはインデントする必要があります。また、他のパラグラフ同様、空白行で前後をかこう必要があります:
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
:: マーカーの扱いはとてもスマートです:
もしマーカーがリテラルコードブロックのパラグラフの中に出てきた場合には、そのパラグラフは完全にそのままドキュメント中に残されます。
もしもマーカーの前がホワイトスペースだった場合には、マーカー自身は非表示になります。
もしもマーカーの前がホワイトスペース以外だった場合には、コロン(:)1つだけが表示されます。
3つ目のルールが適用されるため、上記のサンプルの最初の段落中の２つめの文をレンダリングすると、 “次のパラグラフはコードサンプルです:” という表記になります。
テーブル¶
テーブルの表現方法には2通りあります。 グリッドテーブル (ref)は、セルのグリッドを自分で線描する必要があります。これは次のようになります:
+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+
シンプルテーブル (ref)はより書くのが簡単な方法ですが、制限があります。1つ以上の列を含み、最初のカラムには複数行のテキストを書くことができません。次のように表現されます:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
ハイパーリンク¶
外部リンク¶
`リンクテキスト <http://ターゲットURL>`_ という書くことで、外部のウェブサイトへのリンクを埋め込むことができます。もしリンクテキストがウェブのアドレスである場合には、特別なマークアップは必要ありません。パーサーが通常のテキスト中でリンクか、メールアドレスを見つけると、そのままそれにリンクを埋め込んでくれます。
重要
There must be a space between the link text and the opening < for the URL.
次のようにして、ターゲット定義(ref)と、リンクを分割することもできます:
This is a paragraph that contains `a link`_.
.. _a link: http://example.com/
内部リンク¶
内部リンクはSphinxの提供する、特別なreSTのロールを通じて行われます。詳しくは、特別なマークアップ 自由な場所へのクロスリファレンス のセクションを見てください。
セクション¶
セクションのヘッダ(ref)は、セクションのタイトルを句読点などの記号の文字でアンダーラインを引くことで設定します。必要に応じてでオーバーラインも併用できます。アンダーラインはテキストと同じか、それ以上の長さにする必要があります:
=================
This is a heading
=================
通常は、文字の種類と見出しのレベルは関係ないため、どの文字でも使用することができます。使用していない種類のアンダーラインが出てくると、見出しのレベルが一段変わる、というルールになっています。参考までに、`Pythonドキュメントでのスタイルガイド<https://docs.python.org/devguide/documenting.html#style-guide>`_で用いられる慣例について紹介しておきます:
#部: オーバーライン付き*章: オーバーライン付き=, セクション-, サブセクション^, サブサブセクション", パラグラフ
もちろん、どのようなマークアップ文字を選択しても自由ですし、組み合わせることで、より深いネストレベルも使用できます。reSTの文章を参照してください。ただし、ほとんどの対象となる出力フォーマット(HTML, LaTeX)は、ネストできる深さには限界が設定されている、ということは忘れないでください。
明示的なマークアップ¶
“明示的なマークアップ”(ref)というのは、reSTの中では特別な操作の必要な多くの構成要素のために使用されます。例えば脚注や、言語別のハイライトをする特別な段落、コメントや処理系(Sphinx)に対する指示などです。
明示的なマークアップのブロックは .. で始まる行から始まります。先頭の記号の後ろにはホワイトスペースが一つ入ります。そして、インデントが同じレベルになる次の段落までが１つのブロックとして扱われます。通常のパラグラフと、明示的なマークアップのブロックの間には一行以上のスペースを空ける必要があります。このような説明を聞くとわかりにくいと感じる人も多いと思いますが、実際に自分で書いてみると十分に直感的であるということがわかるでしょう。
ディレクティブ¶
ディレクティブ(ref)は汎用の明示的マークアップです。reSTの拡張のためのメカニズムの一つで、ロールが指定されることがあります。Sphinxはこのディレクティブをかなり多用しています。
Docutilsは次のようなディレクティブを含みます:
警告: attention, caution, danger, error, hint, important, note, tip, warning ,および、一般的な用途の admonition (ほとんどのテーマは、”note”と”warning”にだけスタイルを適用します)。
イメージ:
追加の本体要素:
contents (ローカルな、つまり現在のファイル内だけの、目次)
container (カスタムのクラスを付加できるコンテナ。HTMLで外部の
<div>を生成するのに便利)rubric (ドキュメントのセクションと関係のない見出し)
parsed-literal (インラインマークアップをサポートしたリテラルブロック)
epigraph (追加の属性行を付加できるブロック引用)
highlights, pull-quote (特有のクラス属性を持つブロック引用)
compound (複合パラグラフ)
特別なテーブル:
table (タイトル付きのテーブル)
csv-table (カンマ区切りの値からテーブル生成)
list-table (リストのリストからテーブル生成)
特別なディレクティブ:
HTML定義
疑似命令マークアップ:
default-role (デフォルトのロールをセット)
role (新しいロールの作成)
これらのマークアップの影響範囲は、そのマークアップが書かれたファイルだけに限定されるため、Sphinxが提供する
default_roleを設定する方が良いでしょう。
sectnum, header, footer の3つのディレクティブは使用 しない で下さい。
Sphinxによって追加されたディレクティブに関しては Sphinxマークアップ集 を参照してください。
基本的に、ディレクティブは名前、引数、オプション、コンテンツなどで構成されています。これらの用語を覚えておいてください。これらは次の章でカスタムディレクティブの紹介を行う際に利用します。以下にサンプルを示します:
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function がディレクティブの名前です。ここでは二つの引数が与えられています。1行目の残りの部分と、2行目が引数です。そして1つのオプション module も同様に設定されています。見ての通り、オプションは引数のある行のすぐ次の行に書かれていています。そして、目印としてコロンが付いています。オプションは、ディレクティブのコンテンツと同じインデントの高さにします。
ディレクティブのコンテンツというのは、空白行の後に続くブロックで、ディレクティブが開始された地点よりも深いインデントでくくられています。
画像¶
reSTは画像に関するディレクティブ(ref)もサポートしています。以下のように使用します。:
.. image:: gnu.png
(options)
Sphinx内で使用する場合には、ソースファイルからの相対パスか、トップのソースディレクトリからの絶対パスでファイル名(ここでは gnu.png)を指定します。例えば、 sketch/spam.rst というソースファイルからは、 images/spam.png, ../images/spam.png, /images/spam.png というように書くことができます。
このディレクティブを使用すると、Sphinxはビルド時に、指定された画像ファイルを出力ディレクトリのサブディレクトリにコピーします。HTML出力の場合には、 _static といったディレクトリにコピーされます。
画像サイズのオプション(width と height)は以下のように解釈されます。もしpxなどの単位が無い、もしくは単位がピクセル(px)の場合、ビルダーがその単位をサポートしているかどうかチェックします。例えば、LaTeXビルダーは単位無指定とpxをサポートしていないためサイズ指定は無視されます。比率指定 % や他の単位(ポイントを表す pt など)はHTMLでもLaTeXでも使用できます。
Sphinxは標準のdocutilsを拡張していて、拡張子としてアスタリスク(*)を受け取れるようになっています:
.. image:: gnu.*
アスタリスクが指定されると、Sphinxは指定されたパターンにマッチするすべての画像フォーマットを検索して、使用するタイプを決定します。それぞれのビルダーは、候補となるベストのイメージを選択します。 gnu.* にマッチするファイル名として、 gnu.pdf と、 gnu.png がソースツリーの中に存在していたとします。LaTeXビルダーは前者のPDFを、HTMLビルダーは後者のPNGを優先的に利用します。サポートされている画像タイプと使用優先度は、 利用可能なビルダー で定義されています。
画像ファイルのファイル名にはスペースを含んではいけないことに注意してください。
バージョン 0.4 で変更: ファイル名の末尾をアスタリスク（*）にできる機能が追加されました。
バージョン 0.6 で変更: イメージパスとして、ソースフォルダのルートからの絶対パスが指定できるようになりました。
脚注¶
脚注(ref)を作成するためには、脚注を書きたい場所で [#name]_ というマークアップを書きます。そして、脚注の本体をドキュメントの下の方の “脚注” のためのrubric見出しの中に書きます:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
脚注の数値を明示的に指定([1]_)することもできますし、名前を指定しないで脚注の自動採番([#])をさせることも可能です。
引用¶
標準のreSTでも引用(ref)はサポートしていますが、Sphinx独自の追加の機能としては、引用が”グローバル”ということです。そのため、全ての引用はすべてのファイルから参照できます。以下のように使用します:
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
引用は、脚注と同じように使用できますが、ラベルは数字ではありませんし、 # でも始まりません。
置換¶
reSTは”置換”(ref)をサポートしています。これは、テキスト中の |名前| で指定された箇所に、テキストや、マークアップを挿入します。脚注と同じように明示的なマークアップブロックを使って定義します:
.. |name| replace:: replacement *text*
もしくはこのように書きます:
.. |caution| image:: warning.png
:alt: Warning!
詳しくは reSTリファレンスの置換の説明 を参照してください。
いくつかの置換をすべてのドキュメントで使用したい場合には、置換の宣言を別のファイルに切り出して、 rst_prolog に書くか、その置換を行いたいすべてのドキュメントの冒頭で include ディレクティブを使用してインクルードする方法があります。この場合は、他のソースファイルとは別の拡張子を付けるようにしましょう。同じ拡張子にすると、Sphinxはリンクされていないドキュメントとして警告を出力してしまいます。
Sphinxはデフォルトの置換をいくつか定義しています。詳しくは 置換 を参照してください。
コメント¶
上記の脚注のような適切な構造をしていない明示的マークアップのブロックはすべてコメント(ref)とみなされます:
.. This is a comment.
コメントがスタートした行からインデントすることによって、複数行コメントにできます:
..
This whole indented block
is a comment.
Still in the comment.
ソースエンコーディング¶
エムダッシュ(アルファベットのMと同じ幅を持つダッシュ)や、コピーライトの記号などの特殊記号をreSTに入れる場合にはユニコードの文字として直接入れるのが一番簡単な方法です。Sphinxはデフォルトでは、UTF-8であるとみないしてソースコードを読み込みます。 source_encoding の設定値を変更することで、このデフォルトのエンコーディングを変更できます。
分かっていること¶
reSTのドキュメントを書いていると、良く遭遇する問題がいくつかあります:
インラインマークアップの分離: 上記の説明でも触れていますが、インラインマークアップを付ける領域の前後はテキスト以外の文字(スペース、カッコなど)や、バックスラッシュ(日本語フォントだと円記号)でエスケープしたスペースでくくる必要があります。詳しくは、 the reference を参照してください。
インラインマークアップのネストはできない:
*:func:`foo`* 参照といった書き方はできません。
脚注
| [1] | デフォルトドメインに |