reSturedTextのルール¶
見出し¶
下記のようにします。必要であれば階層を増やしても問題ありません。
========
章見出し
========
節見出し
========
項見出し
--------
各見出しにはリファレンスできるよう、ラベルを記述します。名前が重複しないよう、ラベルは _章-節-項
の形式にします。
<例>
.. _sos:
=====
SOS団
=====
.. _sos-about:
SOS団とは
=========
.. _sos-about-history:
SOS団の歴史
-----------
番号は付与しません。自動的に割り振られます。
Note、Warning¶
noteとwarningのみを用います。それ以外のディレクティブを使いたい場合はissueを上げて協議します。
<例>
.. 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:
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
* - なまえ
- 食べ物
* - 長門
- カレー
* - 小泉
- りんご
なまえ |
食べ物 |
---|---|
長門 |
カレー |
小泉 |
りんご |
参照する場合は :numref:
ロールを用います。
<例>
団員の好きな食べ物を :numref:`foods` に示します。
団員の好きな食べ物を 表 1 に示します。
クロスリファレンス¶
脚注 + :ref:
ロールを用います。
nbsphinx [#ref1]_ を用います。
.. rubric:: 脚注
.. [#ref1] :ref:`nbsphinx`
nbsphinx 2 を用います。
コード¶
コマンドは code-block
ディレクティブを用います。言語名を明記し、 :name:
および :caption:
オプションをつけます。
<例>
.. code-block:: python
:name: zen_of_python
:caption: Zen of Python
import this
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:
11 12 | for num in range(1, 101):
print(fizzbuzz(num))
|
ターミナル¶
次のOSを対象とします。
Windows
macOS
Linux(Ubuntu)
コマンドは code-block
ディレクティブを用い、ハイライトする言語は次のとおりにします。macOSのシンタックスはzshとなっていますが、内容はbashで構いません。
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
> venv\Scripts\activate.ps1