reSturedTextのルール

見出し

下記のようにします。必要であれば階層を増やしても問題ありません。

========
章見出し
========

節見出し
========

項見出し
--------

各見出しにはリファレンスできるよう、ラベルを記述します。名前が重複しないよう、ラベルは _章-節-項 の形式にします。

<例>

.. _sos:

=====
SOS団
=====

.. _sos-about:

SOS団とは
=========

.. _sos-about-history:

SOS団の歴史
-----------

番号は付与しません。自動的に割り振られます。

正)SOS団
誤)第1章 SOS団

Note、Warning

noteとwarningのみを用います。それ以外のディレクティブを使いたい場合はissueを上げて協議します。

"attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning", "admonition"

<例>

.. note:: これはnoteです

   tipsやhintも含みます

注釈

これはnoteです

tipsやhintも含みます

.. warning:: これはwarningです

   attentionやcautionも含みます

警告

これはwarningです

attentionやcautionも含みます

URL

脚注に記載します。 rubric:: ディレクティブは 節(ファイル)の最後 に記載します。

<例>

詳細については公式ドキュメント [#python_org]_ を参照してください。

.. rubric:: 脚注

.. [#python_org] https://docs.python.org/ja/3/index.html

詳細については公式ドキュメント 1 を参照してください。

強調

インラインリテラル ``word``

関数、クラス、引数、値

強い強調 **word**

初出のモジュール、クラス

強調 *word*

上記以外

literalinclude:: ディレクティブで強調する場合は :emphasize-lines: オプションを用います。

<例>

.. literalinclude:: src/example.py
   :caption: example.py
   :language: python
   :emphasize-lines: 1,6-9
   :linenos:
リスト 3 example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
def fizzbuzz(num):
    if num % 3 == 0 and num % 5 == 0:
        return 'FizzBuzz'
    elif num % 3 == 0:
        return 'Fizz'
    elif num % 5 == 0:
        return 'Buzz'
    else:
        return str(num)

for num in range(1, 101):
    print(fizzbuzz(num))

画像

figure:: ディレクティブを用います。 :name: オプションとキャプションをつけます。

<例>

.. figure:: https://www.python.org/static/img/python-logo.png
   :name: python_logo

   ここがキャプションになります

参照する場合は :numref: ロールを用います。

これはPythonの画像です( :numref:`python_logo`

これはPythonの画像です( 図 1

表(テーブル)

次のディレクティブを用います。 :name: オプションとキャプションをつけます。

<例>

  • list-table

  • cst-table

  • table(grid tableはできるだけ使わない)

.. list-table:: 好きな食べ物
   :name: foods
   :header-rows: 1

   * - なまえ
     - 食べ物
   * - 長門
     - カレー
   * - 小泉
     - りんご
表 1 好きな食べ物

なまえ

食べ物

長門

カレー

小泉

りんご

参照する場合は :numref: ロールを用います。

<例>

団員の好きな食べ物を :numref:`foods` に示します。

団員の好きな食べ物を 表 1 に示します。

クロスリファレンス

脚注 + :ref: ロールを用います。

nbsphinx [#ref1]_ を用います。

.. rubric:: 脚注

.. [#ref1] :ref:`nbsphinx`

nbsphinx 2 を用います。

索引

<例>

:index: ロールを用います。

:index:`SOS団` は世界を大いに盛り上げる為の涼宮ハルヒの団です。

SOS団 は世界を大いに盛り上げる為の涼宮ハルヒの団です。

コード

コマンドは code-block ディレクティブを用います。言語名を明記し、 :name: および :caption: オプションをつけます。

<例>

.. code-block:: python
   :name: zen_of_python
   :caption: Zen of Python

   import this
リスト 4 Zen of Python
import this

参照する場合は :numref: ロールを用います。

<例>

:numref:`zen_of_python` を実行します。

リスト 4 を実行します。

Pythonスクリプトを参照する場合は literalinclude:: ディレクティブを用います。 :linenos: オプションで行番号を表示します。コードの途中から切り出す場合は :lines: オプションでとりだす行番号を指定し、 :lineno-start: オプションで行番号を振り直します。

<例>

.. literalinclude:: src/example.py
   :caption: example.py
   :language: python
   :lines: 11-
   :lineno-start: 11
   :linenos:
リスト 5 example.py
11
12
for num in range(1, 101):
    print(fizzbuzz(num))

ターミナル

次のOSを対象とします。

  • Windows

  • macOS

  • Linux(Ubuntu)

コマンドは code-block ディレクティブを用い、ハイライトする言語は次のとおりにします。macOSのシンタックスはzshとなっていますが、内容はbashで構いません。

表 2 ターミナルブロックのルール

OS

言語

caption

プロンプト

Windows

powershell

冒頭に[Win] をつける

>

macOS

zsh

冒頭に[macOS] をつける

$

macOS/Linux

bash

冒頭に[macOS/Linux] をつける

$

Windows/macOS/Linux

bash

冒頭に[Win/macOS/Linux] をつける

$

<例>

.. code-block:: powershell
   :caption: [Win] 仮想環境を有効化

   > venv\Scripts\activate.ps1
リスト 6 [Win] 仮想環境を有効化
> venv\Scripts\activate.ps1

TODO

TODOを残しておく場合は todo:: ディレクティブを用います。

<例>

.. todo:: 宇宙人の正体

   あとで詳しく書く

課題

宇宙人の正体

あとで詳しく書く

脚注

1

https://docs.python.org/ja/3/index.html

2

nbsphinx