1. restructuredtextの書き方メモ

1.1. テキスト装飾

ソース

出力

 
通常

通常

 
*斜体*

斜体 [1]

 
**太字**

太字

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

インラインリテラル

 
:sub:`下付き文字`

通常 下付き文字

 
:sup:`上付き文字`

通常 上付き文字

 
:abbr:`略語 (略語の説明文)`

略語

 
:file:`/path/to/file/`

:file:`/path/to/installed/v.{x}.{y}/bin/`

/path/to/file/

/path/to/installed/v.x.y/bin/

 
:program:`mytool`

mytool

 
:kbd:`Ctrl` + :kbd:`C`

Ctrl + C

 
:menuselection:`Start --> Programs`

Start ‣ Programs

 
:cve:`2020-10735`

CVE 2020-10735

 
:cwe:`787`

CWE 787

 
:rfc:`7231`

RFC 7231

1.2. 引用

ソース
通常

    引用文
出力

通常

引用文

1.3. 定型書式

1.3.1. コマンドライン引数

ソース

出力

 
``mytool`` のオプション

.. program:: mytool

.. option:: -output <path>

    出力先ディレクトリ(コマンドライン引数の定型文)

``yourtool`` のオプション

.. program:: yourtool

.. option:: -output

    出力方法

.. option:: --input

    入力方法

mytool のオプション

--output <path>

出力先ディレクトリ(コマンドライン引数の定型文)

yourtool のオプション

--output

出力方法

--input

入力方法

ヒント

programディレクティブを使用するとoptionラベルで参照するときに同じオプション名も区別して相互参照できる。

1.3.2. 環境変数

ソース

出力

 
.. envvar:: MYTOOL_INSTALLED_PATH

    インストールされたディレクトリパス(環境変数の定型文)
MYTOOL_INSTALLED_PATH

インストールされたディレクトリパス(環境変数の定型文)

1.3.3. 設定ファイル

ソース

出力

 
.. confval:: log-path
    :type: ``string``
    :default: "/var/log/my/tool.log"

    ログの格納場所を指定する。(コンフィグ項目の定型文)
log-path
タイプ:
string
デフォルト:
"/var/log/my/tool.log"

ログの格納場所を指定する。(コンフィグ項目の定型文)

1.4. 箇条書き

ソース

出力

 
- 箇条書き項目1
- 箇条書き項目2
- 箇条書き項目3(サブ項目は空行を入れる)

  - サブ項目1(インデントは引用ブロックより小さくする)
  - サブ項目2

    - サブサブ項目1
    - サブサブ項目2
    - サブサブ項目3

  - サブ項目3(サブ項目を終了する場合は空行を入れる)

- 箇条書き項目4
- 箇条書き項目5

  • 箇条書き項目1

  • 箇条書き項目2

  • 箇条書き項目3(サブ項目は空行を入れる)

    • サブ項目1(サブ項目のインデントは引用ブロックのスペース数より少なくする)

    • サブ項目2

      • サブサブ項目1

      • サブサブ項目2

      • サブサブ項目3

    • サブ項目3(サブ項目を終了する場合は空行を入れる)

  • 箇条書き項目4

  • 箇条書き項目5

1.5. 番号付き箇条書き

ソース

出力

 
#. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト

a. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト

A. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト

i. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト
#. 番号付きリスト

  1. 番号付きリスト

  2. 番号付きリスト

  3. 番号付きリスト

  4. 番号付きリスト

  1. 番号付きリスト

  2. 番号付きリスト

  3. 番号付きリスト

  4. 番号付きリスト

  1. 番号付きリスト

  2. 番号付きリスト

  3. 番号付きリスト

  4. 番号付きリスト

  1. 番号付きリスト

  2. 番号付きリスト

  3. 番号付きリスト

  4. 番号付きリスト

1.6. 定義リスト

ソース

出力

 
:定義1: 定義1の説明
:定義2: 定義2の説明
定義1:

定義1の説明

定義2:

定義2の説明

 
定義1
    定義1の説明

定義2
    定義2の説明
定義1

定義1の説明

定義2

定義2の説明

注釈

定義と説明の間には空行を入れない。空行を入れると引用になる。

1.7. 用語集

ソース

出力

 
.. glossary::
    :sorted:

    用語1
        用語1の説明文

    用語4 : t4
    用語5 : t5
        用語4と用語5の説明文（指定すればソートされる）

    用語2
    用語3
        用語2と用語3の説明文（まとめられる）
用語1

用語1の説明文

用語2
用語3

用語2と用語3の説明文（まとめられる）

用語4
用語5

用語4と用語5の説明文（指定すればソートされる）

1.8. 注釈

ソース

出力

 
.. note:: note

注釈

note

 
.. attention:: attention

注意

attention

 
.. caution:: caution

注意

caution

 
.. warning:: warning

警告

warning

 
.. danger:: danger

危険

danger

 
.. error:: error

エラー

error

 
.. hint:: hint

ヒント

hint

 
.. tip:: tip

Tip

tip

 
.. important:: important

重要

important

 
.. seealso:: seealso

参考

seealso

 
.. admonition:: カスタムタイトル
    :class: note

    classを指定することで注釈タイプを指定できる。

カスタムタイトル

classを指定することで注釈タイプを指定できる。

1.9. ハイパーリンク

ソース

出力

 
URLを直接書く https://github.com/toald11/test-sphinx

URLを直接書く https://github.com/toald11/test-sphinx

 
`表示文字 <https://github.com/toald11/test-sphinx>`_

表示文字

 
:doc:`pdf`

:doc:`表示文字 <pdf>`

LaTeX PDFのカスタマイズ

表示文字

1.10. 脚注

ソース
ツールA [#f1]_ は、ツールB [#f2]_ と互換性がある。

.. [#f1] 脚注1の説明文を書く。脚注1の説明文を書く。脚注1の説明文を書く。
.. [#f2] 脚注2の説明文を書く。脚注2の説明文を書く。脚注2の説明文を書く。
出力

ツールA [2] は、ツールB [3] と互換性がある。

1.11. 相互参照

1.11.1. リスト、図、表への参照

ソース

出力

 
:numref:`list-example-codeblock`

:numref:`fig-example-al-center`

:numref:`fig-example-dark`

:numref:`fig-example-light`

:numref:`uml-example-inline`

:numref:`tab-example-simple`

:numref:`tab-example-csv-table`

:numref:`tab-example-list-table`

リスト 1.1

図 1.1

図 1.2

図 1.3

図 1.4

表 1.1

表 1.2

表 1.3

1.11.2. 章、ラベルへの参照

ソース

出力

 
.. _sec_reference:
相互参照
=============================

参照に関する表現方法を :ref:`sec_reference` で説明する。

参照に関する表現方法を 相互参照 で説明する。

1.11.3. 定型書式への参照

ソース

出力

 
:option:`mytool --output`

:option:`yourtool --output`

:option:`yourtool --input`

:envvar:`MYTOOL_INSTALLED_PATH`

:confval:`log-path`

mytool --output

yourtool --output

yourtool --input

MYTOOL_INSTALLED_PATH

log-path

1.11.4. 用語集への参照

ソース

出力

 
:term:`用語1`

:term:`用語2`

:term:`用語3`

:term:`用語4`

:term:`用語5`

用語1

用語2

用語3

用語4

用語5

1.11.5. 数式への参照

ソース

出力

 
数式 :eq:`math-sample` を参照

数式 (1.1) を参照

1.12. 目次

ソース

出力

 
.. toctree::
    :maxdepth: 2
    :name: toc-top
    :numbered:
    :glob:
    :caption: 目次:

    sample/rst
    sample/theme
    sample/pdf

目次の出力例は Sphinxメモ を参照
glob

目次に正規表現を使用

numbered

目次に章番号を自動付与

1.13. 置換

ソース

出力

 
.. |target| replace:: NetworkModule

このドキュメントは |target| に適用される。

このドキュメントは NetworkModule に適用される。

 
releaseは |release|

versionは |version|

todayは |today|

translation progressは |translation progress|

releaseは 0.1

versionは

todayは 2026年05月05日

translation progressは no translated elements!

1.14. コメント

ソース

出力

 
.. これはコメントです。

..
    複数行のコメントも
    書けます。

1.15. コードブロック

ソース
.. code:: bash

    cd test-sphinx
    python -m uv run sphinx-build -M latexpdfja source/ build/
    echo "Done!"


.. code-block:: bash
    :name: list-example-codeblock
    :caption: code-blockのタイトル
    :linenos:

    cd test-sphinx
    python -m uv run sphinx-build -M latexpdfja source/ build/
    echo "Done!"
出力
cd test-sphinx
python -m uv run sphinx-build -M latexpdfja source/ build/
echo "Done!"
リスト 1.1 code-blockのタイトル
1cd test-sphinx
2python -m uv run sphinx-build -M latexpdfja source/ build/
3echo "Done!"

1.16. 画像

ソース

出力

 
.. figure:: https://avatars.githubusercontent.com/u/40462478
    :name: fig-example-al-center
    :align: center

    画像の貼り付け
https://avatars.githubusercontent.com/u/40462478

図 1.1 画像の貼り付け

 
.. figure:: ../_static/icon_dark.png
    :name: fig-example-dark
    :figclass: only-dark

    ダークテーマの画像

.. figure:: ../_static/icon_light.png
    :name: fig-example-light
    :figclass: only-light

    ライトテーマの画像
../_images/icon_dark.png

図 1.2 ダークテーマの画像

../_images/icon_light.png

図 1.3 ライトテーマの画像

警告

figclassによるダーク/ライトテーマの切り替えは、以下のケースでは有用ではありません。

PDFの出力:

両方の図が出力される。

numfigとの併用:

図の参照番号は共有されない。

1.17. PlantUML

設定

設定例を以下に示す。 特に日本語フォントを使用することに特化した例である。

リスト 1.2 plantumlのインストール
wget openjdk-17-jre-headless fonts-noto-cjk
wget -O /usr/local/bin/plantuml.jar https://github.com/plantuml/plantuml/releases/download/v1.2026.2/plantuml-mit-1.2026.2.jar
リスト 1.3 conf.pyの設定例(日本語設定)
extensions.append("sphinxcontrib.plantuml")
plantuml = 'java -jar /usr/local/bin/plantuml.jar -config /usr/local/share/jp.pu'
リスト 1.4 /usr/local/share/jp.pu の設定例(日本語フォントをデフォルト使用する)
skinparam defaultFontName "Noto Sans CJK JP"
skinparam dpi 100

ソース

出力

 
.. uml::
    :name: uml-example-inline
    :scale: 100 %
    :caption: PlantUMLの出力例

    "A" -> "B" : 日本語の表示には
    "A" -> "B" : フォントのインストールと
    "A" -> "B" : デフォルトフォントの指定が便利

"A" -> "B" : 日本語の表示には "A" -> "B" : フォントのインストールと "A" -> "B" : デフォルトフォントの指定が便利

図 1.4 PlantUMLの出力例

1.18. 表

ソース

出力

 
.. table:: シンプルテーブル
    :name: tab-example-simple
    :widths: 10,70,20

    ======== ======== ========
    header 1 header 2 header 3
    ======== ======== ========
    1        2        3
    4        5        6
    7        8        9
    ======== ======== ========
表 1.1 シンプルテーブル

header 1

header 2

header 3

1

2

3

4

5

6

7

8

9

 
.. csv-table:: CSVテーブル
    :name: tab-example-csv-table
    :header-rows: 1
    :stub-columns: 1
    :widths: 10,70,20

    header 1,header 2,header 3
    1,2,3
    4,5,6
    7,8,9
表 1.2 CSVテーブル

header 1

header 2

header 3

1

2

3

4

5

6

7

8

9

 
.. list-table:: リストテーブル
    :name: tab-example-list-table
    :header-rows: 1
    :stub-columns: 1
    :widths: 10,70,20

    * - header 1
    - header 2
    - header 3
    * - 1
    - 2
    - 3
    * - 4
    - 5
    - 6
    * - 7
    - 8
    - 9
表 1.3 リストテーブル

header 1

header 2

header 3

1

2

3

4

5

6

7

8

9

1.19. 数式

ソース

出力

 
インライン数式 :math:`f = ma^2` は文書中に表示できる

インライン数式 \(f = ma^2\) は文書中に表示できる

 
.. math::
    :label: math-sample

    (a + b)^2 &= a^2 + 2ab + b^2 \\
    (a - b)^2 &= a^2 - 2ab + b^2

.. math::
    :label: math-sample2

    (a + b)(a - b) &= a^2 - b^2 \\
(1.1)\[\begin{split}(a + b)^2 = a^2 + 2ab + b^2 \\ (a - b)^2 = a^2 - 2ab + b^2\end{split}\]
(1.2)\[\begin{split}(a + b)(a - b) = a^2 - b^2 \\\end{split}\]

警告

表の中に数式を入れる場合、等式で整列する &= を使用するとLaTeX PDFを出力する際にエラーになる。

1.20. バージョン表記

ソース
.. version-added:: v1.2.2 :option:`yourtool --input` を追加
.. version-changed:: v1.2.2 :option:`mytool --output` の処理を変更
.. version-deprecated:: v1.2.2 `mytool -o` は、 `mytool --output` に置き換わりました。
.. version-added:: v1.2.1 :option:`yourtool --output` を追加
.. version-removed:: v1.2.1 :option:`yourtool --verbose` を削除
出力

Added in version v1.2.2: yourtool --input を追加

バージョン v1.2.2 で変更: mytool --output の処理を変更

バージョン v1.2.2 で非推奨: mytool -o は、 mytool --output に置き換わりました。

Added in version v1.2.1: yourtool --output を追加

Removed in version v1.2.1: yourtool --verbose を削除