reStructuredTextチートシート

技術系
2017.08.20

どうも、@ta_dragonです。

最近sphinxを触る機会があったのですが、markdownの書き方はわかるのにreStructuredText(通称reST)だとどう書くかわからない！という状況に陥りました。
なので、自分向けのまとめを兼ねてreSTの基本的な文法をMarkdownと比較しながら紹介していきたいと思います。

reSTはsphinxで利用されることが多いと思うので、この記事でもsphinxを利用しています。

見出し

Markdownだとこれ

# 見出し1
## 見出し2
### 見出し3
#### 見出し4

reSTでは、以下の文字のいずれかを、見出しにしたい文字列の下に引くことで見出しになります。

= - ` : ' " ~ ^ _ * + # < >

これらの記号が 出てきた順 で見出しの大きさが決まります。

第一部
######

第一章
******

セクション1
===========

サブセクション1
---------------

サブサブセクション1
^^^^^^^^^^^^^^^^^^^

段落(パラグラフ)
""""""""""""""""

結果 (:numbered:を指定してるので章番号が出てます)

heading

見出しの長さが記号よりも長い場合は怒られます。

出てきた順なので、ルールを決めて使うのが良いと思います。

文字の装飾

Markdownだとこれ

表示 記号 例 出力
太字 ** ** **Bold Text** Bold Text
斜体 * * *Italic Text* Italic Text
取り消し線 ~~ ~~ ~~Strikethrough~~ ~~Strikethrough~~

reSTだと以下

Styling_text

reSTは取り消し線なさそうです。
このブログも対応してなさそうです。

引用文

Markdownだとこれ

ここは普通の文章。

> ここは引用文。

普通の文章。

reSTはインデントします。

ここは普通の文章。

    ここは引用文。

普通の文章。

結果

quote

sphinxでHTMLにする場合、テーマによっては引用印の左の線が出ないかもしれないです。

コードブロック

Markdownだとこれ(インデントしないとうまくエスケープできなかったので、インデントしてます)

    ```
    コードブロック
    ```

reSTでは、コードブロックの直前の段落を記号::で終わらせると次の段落がコードブロックになります。

ここは普通の段落だよ、次の段落がコードブロックになるよ::

   インデントがなくならないかぎり、コードブロックであり続けるよ。
   改行はもちろん、

   空行を挟んだ複数行もできるよ

普通の段落にもどったよ。

結果
code_block

コードサンプル

Markdownだとこれ

    ```c
    #include <stdio.h>

    int main(void) {
        printf("Hello world");
    }
    ```

reSTは、code-blockディレクティブを使います。

.. code-block:: c

   #include <stdio.h>

   int main(void) {
       printf("Hello world");
   }

結果
code_sample.PNG

リンク

Markdownだとこれ

[Google](https://www.google.co.jp/)

reSTだと以下

`Google <https://www.google.co.jp/>`_

最後の_(アンダーバー)は大事です。

分けて書くこともできます。

Google: Google_

.. _Google: https://www.google.co.jp/

リスト

Markdownだとこれ

*/-/+のどれか(ここでは*を利用)
* リスト1
* リスト2
* リスト3

自動ナンバリング
1. 数字リスト1
2. 数字リスト2
3. 数字リスト3

ネスト
* 親リスト
    - 子リスト

reSTだと以下

*/-/+のどれか(ここでは*を利用)

* リスト1
* リスト2
* リスト3

開始数字指定ナンバリング(数字バラバラだと怒られる)

2. 数字リスト1
3. 数字リスト2
4. 数字リスト3

自動ナンバリング

#. 数字リスト1
#. 数字リスト2
#. 数字リスト3

ネスト

* 親リスト

    #. 親子は空白で区切らないと怒られる。

結果

list.PNG

水平線

Markdownだとこれ


===========

-----------

reSTでは、見出しに使える文字を4つ以上並べて前後に空白を置くと水平線になります。

水平線前

===========

水平線引けてる！

画像の埋め込み

Markdownだとこれ

![IMAGE](image.png)

reSTだと、imageディレクティブを使います。

.. image:: ../image.png
   :alt: IMAGE

外部の画像を取ってくることもできそうです。

表

マークダウンだとこれ

| 値 |説明 |
|:--------|------------:|
| 値1 | 説明1 |
| 値2 | 説明2 |
| 値3 | 説明3 |

reSTは二つのテーブルがあります。

グリッドテーブル

+-----+-------+
| 値 | 説明 |
+=====+=======+
| 値1 | 説明1 |
+-----+-------+
| 値2 | 説明2 |
+-----+-------+
| 値3 | 説明3 |
+-----+-------+

シンプルテーブル

==== ======
値 説明
---- ------
値1 説明1
値2 説明2
値3 説明3
==== ======

結果

tables.PNG

グリッドテーブルを引くのは死ぬほどめんどくさいですが、 Text Tables Generator を利用するといくらかましになります。

csv-tableディレクティブを利用してもよいと思います。

数式

Markdownだといくつか方言がありますが、多いのはこれでしょうか。

    ```math
    b = a^e \mod n
    ```

reSTだと、conf.pyに以下を追加した後に、mathディレクティブを利用します。

copy.py内
extensions = ['sphinx.ext.mathjax']

.. math::

b = a^e \mod n

$latex b = a^e \mod n $
RSAの式です。

この記事の内容を載せたrstファイルは ここ に置いておきます。

参考文献

Markdown記法 チートシート
Basic writing and formatting syntax
reStructuredText入門 — Sphinx 1.5.6 ドキュメント
Quick reStructuredText
python-sphinxで表を書く時は csv-table を使った方が便利

コメント