reStructuredText入門¶

reStructuredTextは、Sphinxで使用されるデフォルトのプレーンテキストマークアップ言語です。このセクションでは、reStructuredText (reST) の概念と構文について簡単に説明し、著者が効率的にドキュメントを作成するために必要な情報を提供することを目的としています。reStructuredTextはシンプルで目立たないマークアップ言語として設計されているため、それほど時間はかかりません。

参照

権威のあるreStructuredTextユーザー文書。このドキュメント内の「ref」リンクは、reStructuredTextリファレンスの個々の構成要素の説明へのリンクです。

段落¶

段落(ref)は、reStructuredTextドキュメントの基本的なブロックです。段落は、1つ以上の空行で区切られたテキストの塊です。Pythonと同様に、reStructuredTextではインデントが重要であるため、同じ段落のすべての行は同じインデントレベルに左揃えする必要があります。

インラインマークアップ¶

標準的なreStructuredTextインラインマークアップは非常にシンプルです。

アスタリスク1つ: *text* は強調（斜体）
アスタリスク2つ: **text** は強い強調（太字）
バッククォート: ``text`` はコードサンプル

アスタリスクまたはバッククォートが本文中に表示され、インラインマークアップの区切り記号と混同される可能性がある場合は、バックスラッシュでエスケープする必要があります。

このマークアップにはいくつかの制限があることに注意してください。

ネストできない。
内容は空白文字で始めたり終わったりすることはできません: * text* は間違っています。
周囲のテキストとは単語以外の文字で区切られる必要があります。これを回避するには、バックスラッシュでエスケープされた空白を使用します: thisis\ *one*\ word。

これらの制限は、将来のバージョンのdocutilsで解除される可能性があります。

このインラインマークアップの一部をロールで置き換えたり拡張したりすることも可能です。ロールを参照して詳細を確認してください。

リストと引用ブロック¶

リストマークアップ(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.

用語には、1行以上のテキストを含めることはできません。

引用段落(ref)は、周囲の段落よりも多くインデントするだけで作成できます。

ラインブロック(ref)は、改行を保持する方法です。

| These lines are
| broken exactly like in
| the source file.

他にもいくつかの特別なブロックがあります。

フィールドリスト(ref、フィールドリストで説明されている注意事項付き)
オプションリスト(ref)
引用リテラルブロック(ref)
doctestブロック(ref)

リテラルブロック¶

リテラルコードブロック(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つに置き換えられます。

このようにして、上記の例の先頭段落の2番目の文は「次の段落はコードサンプルです：」と表示されます。

これらのリテラルブロックのコード強調表示は、highlightディレクティブを使用してドキュメント全体で有効にしたり、highlight_language設定オプションを使用してプロジェクト全体で有効にしたりできます。code-blockディレクティブを使用して、ブロックごとに強調表示を設定できます。これらのディレクティブについては、後で説明します。

Doctestブロック¶

Doctestブロック(ref)は、docstringにカットアンドペーストされた対話型のPythonセッションです。リテラルブロック構文は必要ありません。doctestブロックは空行で終わる必要があり、使用されていないプロンプトで終わってはなりません。

>>> 1 + 1
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)は記述が容易ですが、制限があります。2行以上含まれている必要があり、最初の列のセルには複数行を含めることができません。次のようになります。

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

さらに2つの構文がサポートされています：CSV表とリスト表。これらは明示的マークアップブロックを使用します。表を参照して詳細を確認してください。

ハイパーリンク¶

外部リンク¶

インラインウェブリンクには`Link text <https://domain.invalid/>`_を使用します。リンクテキストをウェブアドレスにする必要がある場合は、特別なマークアップは必要ありません。パーサーは通常のテキストからリンクとメールアドレスを見つけます。

重要

URLの開始<記号の前には、リンクテキストとの間にスペースが必要です。

リンクとターゲット定義(ref)を次のように分離することもできます。

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/

内部リンク¶

内部リンクは、Sphinxによって提供される特別なreStructuredTextロールを介して行われます。特定のマークアップに関するセクション任意の場所の相互参照を参照してください。

セクション¶

セクション見出し(ref)は、セクションタイトルを句読点記号で下線（およびオプションで上線）を引くことによって作成されます。少なくともテキストと同じ長さが必要です。

=================
This is a heading
=================

通常、構造は見出しの連続から決定されるため、特定の文字に見出しレベルは割り当てられていません。ただし、この規則はPython開発者向けドキュメント作成ガイドで使用されており、従うことができます。

#を上線付きで、パート用
*を上線付きで、章用
=をセクション用
-をサブセクション用
^をサブサブセクション用
"を段落用

もちろん、独自のマーカ文字を使用したり（reStructuredTextドキュメントを参照）、より深いネストレベルを使用したりできますが、ほとんどのターゲット形式（HTML、LaTeX）にはサポートされているネストの深さに制限があることに注意してください。

フィールドリスト¶

フィールドリスト(ref)は、次のようにマークアップされたフィールドのシーケンスです。

:fieldname: Field content

Pythonのドキュメントで一般的に使用されています。

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

Sphinxは標準のdocutilsの動作を拡張し、ドキュメントの先頭で指定されたフィールドリストをインターセプトします。フィールドリストを参照して詳細を確認してください。

ロール¶

役割、または「カスタム解釈テキスト役割」( 参照 )は、明示的なマークアップのインライン部分です。これは、囲まれたテキストを特定の方法で解釈する必要があることを示します。Sphinx はこれを使用して、適切なセクションで説明されているように、セマンティックマークアップと識別子の相互参照を提供します。一般的な構文は:rolename:`content`です。

Docutils は次の役割をサポートしています。

emphasis – *emphasis*と同等です。
strong – **strong**と同等です。
literal – ``literal``と同等です。
subscript – 下付き文字。
superscript – 上付き文字。
title-reference – 書籍、定期刊行物、その他の資料のタイトル用。

Sphinx によって追加された役割については、役割を参照してください。

明示的マークアップ¶

「明示的マークアップ」( 参照 )は、脚注、特に強調表示された段落、コメント、一般的なディレクティブなど、特別な処理が必要なほとんどの構成要素でreStructuredTextで使用されます。

明示的マークアップブロックは、..で始まる行と空白で始まり、同じインデントレベルの次の段落で終了します。(明示的マークアップと通常の段落の間に空行が必要です。これはやや複雑に聞こえるかもしれませんが、記述する際には十分直感的です。)

ディレクティブ¶

ディレクティブ( 参照 )は、明示的マークアップの一般的なブロックです。役割と同様に、reStructuredTextの拡張メカニズムの1つであり、Sphinx はこれを多用します。

Docutils は次のディレクティブをサポートしています。

注意書き: attention、caution、danger、error、hint、important、note、tip、warning、および一般的なadmonition。(ほとんどのテーマでは、「note」と「warning」のみが特別にスタイル設定されます。)
画像
- image (下記の画像も参照)
- figure (キャプションとオプションの凡例付きの画像)
追加の本文要素
- contents (ローカル、つまり現在のファイルのみの目次)
- container (カスタムクラスを持つコンテナ。HTMLで外部の<div>を生成するのに役立ちます)
- rubric (ドキュメントのセクション分割とは関係のない見出し)
- topic、sidebar (特別な強調表示された本文要素)
- parsed-literal (インラインマークアップをサポートするリテラルブロック)
- epigraph (オプションの引用句付きのブロック引用)
- highlights、pull-quote (独自のclass属性を持つブロック引用)
- compound (複合段落)
特別な表
- table (タイトル付きの表)
- csv-table (コンマ区切り値から生成された表)
- list-table (リストのリストから生成された表)
特別なディレクティブ
- raw (生のターゲット形式のマークアップを含める)
- include (別のファイルからreStructuredTextを含める) – Sphinxでは、絶対的なインクルードファイルパスが指定されると、このディレクティブはソースディレクトリに対する相対パスとして扱われます。
- class (次の要素にclass属性を割り当てる)
  
  注記
  
  デフォルトドメインにclassディレクティブが含まれている場合、このディレクティブは隠されます。そのため、Sphinx はこれをrst-classとして再エクスポートします。
  
  ヒント
  
  ディレクティブにクラスを追加する場合は、:class: オプションを検討してください。これはほとんどのディレクティブでサポートされており、よりコンパクトな表記を可能にします。
HTMLの仕様
- meta (HTML <meta> タグの生成、下記のHTMLメタデータも参照)
- title (ドキュメントタイトルの上書き)
マークアップへの影響
- default-role (新しいデフォルトの役割を設定する)
- role (新しい役割を作成する)
これらはファイルごとにのみ有効であるため、default_roleの設定にはSphinxの機能を使用することをお勧めします。

警告

sectnum、header、footerのディレクティブは使用しないでください。

Sphinx によって追加されたディレクティブについては、ディレクティブを参照してください。

基本的に、ディレクティブは名前、引数、オプション、およびコンテンツで構成されます。(この用語を覚えておいてください。これは、カスタムディレクティブについて説明する次の章で使用されます。) この例を見ると、

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.

functionはディレクティブ名です。ここでは、最初の行の残りと2行目が2つの引数として渡され、moduleという1つのオプションが渡されています。(ご覧のとおり、オプションは引数の直後の行に指定され、コロンで示されます)。オプションは、ディレクティブコンテンツと同じレベルでインデントする必要があります。

ディレクティブコンテンツは、空行の後に続き、ディレクティブの開始位置を基準に、またはオプションが存在する場合はオプションと同じ量だけインデントされます。

インデントは、たとえば3つのスペースという固定数の空白ではなく、任意の数の空白であることに注意してください。ドキュメント全体で固定インデントが使用されている場合、これは驚くべきことであり、空白に影響を受けるディレクティブにとって違いが生じる可能性があります。比較すると

.. code-block::
   :caption: A cool example

       The output of this line starts with four spaces.

.. code-block::

       The output of this line has no spaces at the beginning.

最初のコードブロックでは、コンテンツのインデントはオプション行によって3つのスペースに固定されていたため、コンテンツは4つのスペースで始まります。後者では、インデントはコンテンツ自体によって7つのスペースに固定されていたため、スペースで始まりません。

画像¶

reStructuredTextは、次のように使用される画像ディレクティブ( 参照 )をサポートしています。

.. image:: gnu.png
   (options)

Sphinx内で使用する場合、指定されたファイル名(ここではgnu.png)は、ソースファイルに対する相対パス、または最上位ソースディレクトリに対する相対パスである必要があります。たとえば、sketch/spam.rstというファイルは、../images/spam.pngまたは/images/spam.pngとして画像images/spam.pngを参照できます。

Sphinxは、ビルド時に画像ファイルを自動的に出力ディレクトリのサブディレクトリ(たとえば、HTML出力の場合は_staticディレクトリ)にコピーします。

画像サイズオプション（width および height）の解釈は以下のとおりです。サイズに単位がない場合、または単位がピクセルである場合、指定されたサイズはピクセルをサポートする出力チャネルに対してのみ適用されます。その他の単位（pt（ポイント）など）は、HTML および LaTeX 出力に使用されます（後者は pt を bp に置き換えます。これは TeX の単位で、72bp=1in となります）。

Sphinx は、拡張子にアスタリスクを使用することを許可することで、標準的な docutils の動作を拡張します。

.. image:: gnu.*

その後、Sphinx は指定されたパターンに一致するすべての画像を検索し、その種類を判別します。各ビルダーは、これらの候補の中から最適な画像を選択します。たとえば、ファイル名 gnu.* が指定されていて、ソースツリーに gnu.pdf と gnu.png の2つのファイルが存在する場合、LaTeX ビルダーは前者を選択し、HTML ビルダーは後者を選択します。サポートされている画像の種類と選択の優先順位は、ビルダーで定義されています。

画像ファイル名にはスペースを含めないでください。

バージョン 0.4 で変更: アスタリスクで終わるファイル名のサポートを追加しました。

バージョン 0.6 で変更: 画像パスは絶対パスにすることができます。

バージョン 1.5 で変更: latex ターゲットはピクセルをサポートします（デフォルトは 96px=1in）。

脚注¶

脚注（ref）には、[#name]_ を使用して脚注の位置をマークし、本文の末尾に「脚注」の見出しの後に脚注本文を追加します。

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

脚注に明示的に番号を付けることもできます（[1]_）。または、名前のない自動番号付けされた脚注を使用することもできます（[#]_）。

引用¶

標準的な reStructuredText 引用（ref）がサポートされています。追加機能として、「グローバル」である、つまりすべての引用がすべてのファイルから参照できるようになっています。以下のように使用します。

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

引用の使い方は脚注と似ていますが、数値ではないか、#で始まるラベルを使用します。

置換¶

reStructuredText は「置換」（ref）をサポートしています。これは、テキスト内で |name| で参照されるテキストやマークアップの部分です。脚注のように明示的なマークアップブロックで定義されます。

.. |name| replace:: replacement *text*

またはこれ

.. |caution| image:: warning.png
             :alt: Warning!

詳細は、reStructuredText の置換に関する参照を参照してください。

すべてのドキュメントで置換を使用する場合は、rst_prologまたはrst_epilogに配置するか、別ファイルに配置し、include ディレクティブを使用して使用したいすべてのドキュメントに含めます。（Sphinx がスタンドアロンのドキュメントとして見つけるのを避けるために、include ファイルには、他のソースファイルとは異なるファイル名拡張子を使用してください）。

Sphinx はいくつかのデフォルトの置換を定義しています。置換を参照してください。

コメント¶

有効なマークアップ構造ではないすべての明示的なマークアップブロック（上記の脚注など）は、コメントとして扱われます（ref）。例えば

.. This is a comment.

コメントの開始後にテキストをインデントして、複数行コメントを作成できます。

..
   This whole indented block
   is a comment.

   Still in the comment.

HTML メタデータ¶

meta ディレクティブを使用すると、Sphinx ドキュメントページの HTML メタデータ要素を指定できます。たとえば、以下のディレクティブ

.. meta::
   :description: The Sphinx documentation builder
   :keywords: Sphinx, documentation, builder

は、次の HTML 出力を生成します。

<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">

また、Sphinx は meta ディレクティブで指定されたキーワードを検索インデックスに追加します。その際、meta 要素の lang 属性が考慮されます。たとえば、以下のディレクティブ

.. meta::
   :keywords: backup
   :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
   :keywords lang=de: bittediesenkeyfinden

は、異なる言語設定を持つビルドの検索インデックスに次の単語を追加します。

pleasefindthiskey、pleasefindthiskeytoo を英語のビルドに；
bittediesenkeyfinden をドイツ語のビルドに；
backup をすべての言語のビルドに。

ソースエンコーディング¶

reStructuredText に長いダッシュや著作権記号などの特殊文字を含める最も簡単な方法は、Unicode 文字として直接記述することであるため、エンコーディングを指定する必要があります。Sphinx はデフォルトでソースファイルが UTF-8 でエンコードされていると想定しています。これは、source_encoding 設定値で変更できます。

注意点¶

reStructuredText ドキュメントの作成中に一般的に発生するいくつかの問題があります。

**インラインマークアップの分離:** 上記のように、インラインマークアップの範囲は周囲のテキストから単語以外の文字で区切る必要があります。そのためには、バックスラッシュでエスケープされたスペースを使用する必要があります。参照で詳細を確認してください。
**インラインマークアップのネスト不可:** *see :func:`foo`* のようなことはできません。