ここでは、自分がよく使う書き方を集めてみました。
セクション名となる文字列の下に、-や=で線を引きます。これでセクションを作ることができます。
セクションは全部で６レベル分作ることができ、出現した順番にレベル分けされます。
セクション名に使用できる記号はたくさんありますが、見やすさから:
= - ` : . ' " ~ ^ _ * + #
これらが推奨されているようです。
=====================
セクション(レベル１)
=====================
レベル２
========
レベル３
--------
レベル４
^^^^^^^^
出力例
| 強調 | 文字列 | *で囲む | <em> |
| 強い強調 | 文字列 | **で囲む | <strong> |
| コード | 文字列 | ``で囲む | <span class=”pre”> |
前の段落より１段インデントが深い段落は引用になります。:
以下は引用文です。
こんにちは
こんにちは
こんにちは
ここは引用文ではありません。
以下は引用文です。
こんにちは こんにちは こんにちは
ここは引用文ではありません。
改行をそのまま表示したい場合には、ラインブロックを使います。
| これらの行は、
| ソースファイルと同じように
| 改行されます。
*、+、-を使って項目を並べるとリストになります。
* 項目1
* 項目2
* 項目3
+ 項目1
+ 項目2
- 項目3
出力例
::のあと１行開けてから１段インデントして書く。
ふつうの文章::
コードブロック
ふつうの文章
またはcode-blockディレクティブを使います。:
.. code-block:: python
import sys
print sys.path
code-blockディレクティブではどのシンタックスハイライトを使うかを指定することができます。
文章中で他の文章にリンクを張りたい場合があると思います。
その場合、 ラベル をつけておき、そこに対してrefでリンクを作ることができます。
.. _label:
タイトル
=========
文章
:ref:`label` を参照
以下はサンプルです。
ラベルを張ったところではなく、別の文書へのリンクを作りたい場合には、次のように書きます。
:doc:`03`
上記のように書くと「 ハンズオン：勉強会レポートを作成しよう 」というリンクが出来ます。
次のようにリンクを書くことができます。:
資料
====
* http://sphinx-doc.org/
* `github <https://github.com>`_
* Sphinx-users.jp_
.. _Sphinx-users.jp: http://sphinx-users.jp/
どの方法が良いというわけはありません。
3の方法は同じ文言を同じリンクにしたい場合には 有効ですが、文字列と実際のリンクURLが離れてしまう欠点もあります。
逆に、2の方法で、同じ文字列に対して2回書いてしまうと、ビルド時に警告がでます。
以下のように書きます。:
:download:`このファイル <03.rst>`
「 このファイル 」のようにリンクが出来ます。
また、リンクだけでなく、出力ディレクトリに_downloadsディレクトリが作成され、 その中にdownloadで指定したファイルが格納されます。
======= ====== ======
col1 col2 col3
======= ====== ======
row1 a b
row2 a b
row3 a b
======= ====== ======
| col1 | col2 | col3 |
|---|---|---|
| row1 | a | b |
| row2 | a | b |
| row3 | a | b |
+------------------------+------------+----------+----------+
| 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 | ... | ... | |
+------------------------+------------+----------+----------+
| Header row, column 1 (header rows optional) | Header 2 | Header 3 | Header 4 |
|---|---|---|---|
| body row 1, column 1 | column 2 | column 3 | column 4 |
| body row 2 | ... | ... |
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn’t be crunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn’t be crunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
ファイルをreStructuredTextとして取り込みたい場合には includeを使用します。
.. include:: include.rst
includeされました
ファイルを引用として取り込みたい場合には、literalincludeを使用します。
.. literalinclude:: include.rst
:language: rst
:linenos:
1 | **includeされました**
|