🧐

【Sphinx】reStructuredText記法チートシート

2024/11/22に公開

Sphinx

tech

reStructuredText記法における，基本的なものをまとめたものです。
随時内容は更新していきたいと思います。

見出し

reSTでは記号の種類や順序により見出しのレベルを自動的に決定します。そのため使用する記号は自由なのですが，Pythonドキュメントでは以下に示す規則が推奨されています。

また，この記号の長さはタイトルの文字数以上である必要があります。

##############################
Parts （ex: タイトル）
##############################

******************************
Chapters （ex: 第1章: 基本事項）
******************************

Sections （ex: はじめに）
==============================

Subsections （ex: reSTとは?）
------------------------------

Subsubsections （ex: reSTの歴史）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Papragraphs （ex: Note）
""""""""""""""""""""""""""""""

もちろん上の例はあくまで推奨です。はじめの2つはタイトルを記号で挟む形で使ってますが，下だけでも問題ありません。

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

始めか終わりに空白があるのはダメ。

イタリック

*これはイタリック体です*

太字

**これは太字です**

コード

``variable``

コードブロック

前の文章を::で終了し，空白行を挟んだ後，インデントしてから始めます。空白行を挟んで同じインデントに戻ると，コードブロックは終わります。
なおこの::ですが，文章の一部で使用された場合，:にレンダリングされ，独立した行で使用した場合は完全に消えます。

以下がコードブロックの例です::

    print("Hello, World!")
    for i in range(5):
        print(i)

同じインデントに戻ると終わります。

レンダリングした際の「:」を消したい場合は「::」を次の行に書きます。
::

    print("Hello, World!")

これで「:」は表示されません。

これは少々分かりづらいので，出力したときのイメージをおいておきます。

コードブロックの言語を指定する場合は，後述するDirectiveを使用します。

表

簡易版と2つの表記法があります。

自分で頑張って書く方法

+------------------------+------------+----------+----------+
| 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             | ...        | ...      |          |
+------------------------+------------+----------+----------+

簡易版

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

簡易版のほうがはるかに楽ですが，以下の制限があるようです。

複数行にする必要がある
最初の行は1行にする

また，tabularcolumnsDirectiveという別の表記もあるようですので，興味のある方は調べて見てください。（私はあまり表を使わない）

リンク

直で貼り付ける際は前後に半角スペースを空けます。

詳細は https://sphinx-users.jp/reverse-dict/writing/link.html を参照してください。

文字列にリンクを結びつけたいときは，以下のインライン記法が使えます。

`Sphinxの日本ユーザ会サイト <http://sphinx-users.jp>`__

最後の__も含めるので注意。
また、前後とリンクの間にスペースを空ける必要がありますので、エラーが出たらまずそこを疑ってください。

~~~~ `mojiretsu <link>`__ ~~~

その他，参考文献としての表現や画像にリンクを結びつける方法もありますので，詳細はこちらを参照ください。

Directive

Directiveは，..で始まるreSTで使用される特殊な構文で，特定の動作や機能を埋め込むための指示を与えます。
色々あるので，ここでは基本的なものを簡単に紹介します。（随時更新していきます）
詳しくはSphinxのドキュメントを見ると良いかと思います。オプションや拡張機能も様々あるので，Directiveに関しては直接ドキュメントを見たほうが早いかもしれません。

基本的な構造

.. directive-name:: arguments
   :option-name: value
   :option-name2: value

   Contents...

目次[toctree]

.. toctree::
    :maxdepth: "number"  ←目次を表示する深さ
    :caption: "text"　   ←キャプションを追加
    :numbered:           ←セクション番号を表示

警告・注意・ヒントなど

おなじみ警告やヒントのブロックです。どのような外観になるかはこちらのドキュメントか，お手元の環境で確認ください。

.. attention::
.. caution::
.. danger::
.. error::
.. hint::
.. important::
.. note::
.. tip::
.. warning::
.. admonition::
.. seealso::

コード・ブロック[code-block, sourcecode, code]

.. code-block:: [language]
.. sourcecode:: [language]
.. code:: [language]

例

.. code-block:: "language"
    :linenos:                              ←行番号を表示
    :emphasize-lines: "行番号（コンマ区切り）" ←特定の行をハイライト

参考

[1]: reStructuredText markup
[2]: Prism
[3]: reStructuredText Markup Specification
[4]: reStructuredText Primer — Sphinx documentation

【Sphinx】reStructuredText記法チートシート

見出し

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

イタリック

太字

コード

リスト

箇条書き

順序付けリスト

フィールド・リスト