reStructuredTextの書き方

.rst は reStructuredText 形式のテキストで、Sphinx のドキュメントでよく使われます。
Markdownより少し厳密ですが、見出し・箇条書き・リンク・コード・表・画像などをかなり柔軟に書けます。

1. 基本ルール

拡張子は .rst
プレーンテキストで書く
構造は 記号の並び で表す
Sphinx では index.rst が入口になることが多い

2. 見出し

見出しは、文字の上下または下に記号を並べて書きます。
よく使うのは以下です。

   タイトル
   ========

   大見出し
   ========

   中見出し
   --------

   小見出し
   ~~~~~~~~

   さらに細かい見出し
   ^^^^^^^^^^^^^^^^

記号の種類に厳密な意味はなく、同じ階層では同じ記号を使うのが大事です。

   例:

   My Document
   ===========

   Section 1
   ---------

   Subsection
   ~~~~~~~~~~

---

3. 段落

普通に空行を入れれば段落になります。

   これは1つ目の段落です。

   これは2つ目の段落です。

改行だけでは段落は分かれません。
段落を変えるときは空行が必要です。

4. 強調

イタリック

   *italic*

太字

   **bold**

等幅文字

   ``code``

例:

   これは *強調* です。
   これは **太字** です。
   これは ``sample.py`` です。

5. 箇条書き

記号付きリスト

   - item 1
   - item 2
   - item 3

または

   * item 1
   * item 2

番号付きリスト

first
second
third

入れ子

インデントを揃えます。

   - item 1
     - sub item 1
     - sub item 2
   - item 2

6. リンク

URLをそのまま書く

   https://www.python.org/

名前付きリンク

   `Python <https://www.python.org/>`_

末尾の _ を忘れないのがポイントです。

7. コードブロック

コードを書くときは :: を使います。

   以下はPythonコードです::

      def hello():
          print("Hello")

:: の次に空行を入れ、
コード本体はインデントします。

Sphinxで言語指定する場合

   .. code-block:: python

      def hello():
          print("Hello")

こちらの方がシンタックスハイライトされるので、Sphinxではよく使います。

8. 引用

   This is a quote::

       quoted text here

単純な引用なら、.. epigraph:: なども使えますが、通常は code-block 的なインデント記法より、用途に応じたディレクティブを使います。

9. 改行と空白

.rst では空白やインデントが重要です。

段落を分けるには空行
ディレクティブの中身はインデント
箇条書きの子要素もインデント

たとえば以下は正しい書き方です。

  - item

    これは item の説明です。

  - next item

10. 画像

Sphinxやdocutilsで画像を入れるには次のように書きます。

  .. image:: images/sample.png
     :width: 400px
     :alt: sample image

中央寄せしたいときは:

  .. image:: images/sample.png
     :align: center

11. 表

シンプル表

  =====  =====
  col1   col2
  =====  =====
  A      10
  B      20
  =====  =====

グリッド表

  +------+------+
  | col1 | col2 |
  +======+======+
  | A    | 10   |
  +------+------+
  | B    | 20   |
  +------+------+

Markdownより少し面倒ですが、複雑な表も書けます。

12. 注釈・メモ

note

  .. note::

      これは補足です。

warning

  .. warning::

      これは注意です。

tip

  .. tip::

      便利な書き方です。

これらは ディレクティブ と呼ばれます。

13. よく使うSphinxディレクティブ

toctree

複数ページをまとめるときに使います。

  .. toctree::
     :maxdepth: 2
     :caption: Contents:

     intro
     usage
     api

拡張子 .rst は通常書かない
intro.rst, usage.rst などを参照する

contents

ページ内目次を出したい場合:

  .. contents::
     :local:
     :depth: 2

14. ラベルと内部リンク

ラベルを付ける

  .. _my-section:

  My Section
  ==========

参照する

  詳しくは :ref:`my-section` を参照してください。

これは Sphinx で非常によく使います。

15. ファイルへのダウンロードリンク

  :download:`sample file <files/data.csv>`

16. 数式

Sphinxで数式拡張を有効にしていれば書けます。

インライン数式

  :math:`E = mc^2`

別行数式

  .. math::

      E = mc^2

複数行も書けます。

  .. math::

      f(x) = \int_0^\infty e^{-t} dt

17. 置換（replacement）

よく使う語を置き換えられます。

  .. |project| replace:: MyProject

  This is |project| documentation.

18. コメント

コメントは以下のように書けます。

  .. これはコメントです

Sphinx出力には通常出ません。

19. include

他の rst ファイルを読み込めます。

  .. include:: common_defs.rst

20. 典型的な index.rst の例

  My Project
  ==========

  Welcome to the documentation.

  .. toctree::
     :maxdepth: 2
     :caption: Contents:

     introduction
     installation
     usage
     api

21. 典型的な説明ページの例

  Installation
  ============

  このページではインストール方法を説明します。

  Requirements
  ------------

  必要な環境は以下です。

  - Python 3.11
  - Sphinx
  - pip

  Install
  -------

  以下を実行します::

      pip install sphinx

  または:

  .. code-block:: bash

      pip install sphinx

  Next Step
  ---------

  詳細は :ref:`usage-page` を参照してください。

22. よくあるエラー

インデント不足

ディレクティブの中身がインデントされていない。

誤り:

  .. note::
  これはメモです

正しい例:

  .. note::

      これはメモです

空行不足

:: やディレクティブの後に空行が必要なことが多いです。

見出し記号の長さ不足

見出し文字数以上の長さで下線を書くのが安全です。

誤り:

  Title
  ===

正しい例:

  Title
  =====

23. Markdownに近い感覚で覚える最小セット

まずはこれだけ覚えれば十分です。

見出し
箇条書き
*italic*, **bold**, code
.. code-block:: python
.. note::
.. toctree::
:ref:
.. math::

24. 最小サンプル

  Sample Document
  ===============

  これはサンプルです。

  Section
  -------

  - item 1
  - item 2

  コード例:

  .. code-block:: python

      def add(a, b):
          return a + b

  数式:

  .. math::

      a^2 + b^2 = c^2

  注意:

  .. note::

      これはサンプルの note です。

25. Sphinx向けの実用メモ

ページ一覧は toctree で管理する
セクション参照は :ref: を使う
API文書では autodoc を併用することが多い
複数の index_*.rst を作る場合、toctree の重複参照に注意する
next/prev を消したいときは Sphinx テーマ設定や html_theme_options を調整することが多い

26. すぐ使えるテンプレート

  Document Title
  ==============

  概要説明を書く。

  .. contents::
     :local:
     :depth: 2

  Section 1
  ---------

  本文を書く。

  - 箇条書き
  - 箇条書き

  Section 2
  ---------

  コード例:

  .. code-block:: python

      print("hello")

  Section 3
  ---------

  数式:

  .. math::

      y = ax + b

  .. note::

      必要に応じて補足を書く。