2. 書式

2.1. 見出し

2.1.1. H1 (見出し1、タイトル)

H1レベルの見出しを表現する書式です。

記載方法

タイトルの上下にタイトルの文字数と同じ幅だけ = (イコール)を記述します。

記述例

========
タイトル
========

表示結果

本ページのタイトルを参照してください。

2.1.2. H2 (見出し2)

H2レベルの見出しを表現する書式です。

記載方法

見出しの下に見出しの文字数と同じ幅だけ = (イコール)を記述します。

記述例

見出し2
=======

2.1.3. H3 (見出し3)

H3ベルの見出しを表現する書式です。

記載方法

見出しの下に見出しの文字数と同じ幅だけ - (ハイフン)を記述します。

記述例

見出し3
-------

2.1.4. H4 (見出し4)

H4レベルの見出しを表現する書式です。

記載方法

見出しの下に見出しの文字数と同じ幅だけ ^ (キャレット)を記述します。

記述例

見出し4
^^^^^^^

2.1.5. H5 (見出し5)

H5レベルの見出しを表現する書式です。

記載方法

見出しの下に見出しの文字数と同じ幅だけ * (アスタリスク)を記述します。

記述例

見出し5
*******

2.1.6. H6 (見出し6) 以上の表現

H6レベル以上の見出し(H6を含む)は使ってはなりません。

危険

通常、H6レベル以上の見出しになる場合は、文章の構造が複雑過ぎています。
書き方を工夫するなどしてH6レベル以上を使わないようにしなければなりません。

2.2. 見出し2から見出し5までの表示例

2.2.1. 見出し3

見出し4

見出し5
見出し6

2.3. パラグラフ

すべての文章はパラグラフ上に記載される必要があります。

2.3.1. 説明

記載方法

文章の先頭に | (パイプ+スペース)を記載します。

記述例

| パラグラフはじまり
| つづきのパラグラ

| 第二パラグラフ

見出
  | 内容1
  | 内容2

表示結果

第1パラグラフ1行目。
第1パラグラフ2行目。
第2パラグラフ1行目。
第2パラグラフ2行目。
見出
内容1
内容2

2.4. タブ

説明をする上で選択肢が有る場合などに利用します。

2.4.1. 説明

記載方法

下記のように .. tabs:: でディレクティブを定義します。

記述例

Hello world を出力するプログラム

.. tabs::

   .. tab:: C言語

      :kbd:`printf` を使います。

      .. code-block:: c
         :caption: helloworld.c
         :linenos:

         #include <stdio.h>

         main()
         {
            printf("Hello World\n");
         }

   .. tab:: シェルスクリプト

      :kbd:`echo` を使用します。

      .. code-block:: shell
         :caption: helloworld.sh
         :linenos:

         #!/bin/bash
         echo "Hello World"
         exit 0

   .. tab:: Python

      :kbd:`print` を使います。

      .. code-block:: python
         :caption: helloworld.py
         :linenos:

         print("Hello World")

表示結果

Hello world を出力するプログラム

printf を使います。

リスト 2.87 helloworld.c
1#include <stdio.h>
2
3main()
4{
5   printf("Hello World\n");
6}

2.5. コード

2.5.1. 説明

ファイル内のソースコードやコマンドなどを表現する際に利用します。

記載方法

下記のように .. code-block:: [コードの言語] でディレクティブを定義します。
オプションは下記のとおりです。
表 2.108 code-block のオプション

オプション

説明

設定値

name

参照の定義

exastro_yaml

caption

ファイル名

(例) exastro.yaml

linenos

行数表示の有無

(不要)

lineno-start

行数表示の開始行番号

5 (数値)

emphasize-lines

コード内の特定の行を強調

12,13 (行の範囲)

注釈

code-block の定義と実際のコードは1行空行を空ける必要があります。
インデントは半角スペース3文字分必要です。

記述例

.. code-block:: yaml
   :name: exastro_yaml
   :caption: exastro.yaml
   :linenos:
   :lineno-start: 5
   :emphasize-lines: 12,13

   # Default values for Exastro.
   # This is a YAML-formatted file.
   # Declare variables to be passed into your templates.
   global:
     itaGlobalDefinition:
       name: ita-global
       enabled: true
       image:
         registry: "docker.io"
         organization: exastro
         package: exastro-it-automation
       config:
         DEFAULT_LANGUAGE: "ja"
         LANGUAGE: "en"

表示結果

リスト 2.90 exastro.yaml
 5# Default values for Exastro.
 6# This is a YAML-formatted file.
 7# Declare variables to be passed into your templates.
 8global:
 9  itaGlobalDefinition:
10    name: ita-global
11    enabled: true
12    image:
13      registry: "docker.io"
14      organization: exastro
15      package: exastro-it-automation
16    config:
17      DEFAULT_LANGUAGE: "ja"
18      LANGUAGE: "en"

2.6. 単語表現

本マニュアルでは、内容に応じて下記のような表現方法を用います。
表 2.109 単語表現

名前

表現例

書式

実際の表記(入力例)

menuselection

メニュー・画面・画面内の項目
:menuselection:`メニュー --> サブメニュー`
:menuselection:`画面名`
:menuselection:`項目`
メニュー ▶ サブメニュー
画面名
項目

guilabel

ボタン

:guilabel:`ボタン`

ボタン

kbd

キーボード入力
:kbd:`Ctrl + Z`
:kbd:`入力文字列`
Ctrl + Z
入力文字列

program

GUI上の設定項目・設定値
:program:`Item`
:program:`Input data`
Item
Input data

file

ファイル・ディレクトリのパス

:file:`/path/to/file`

/path/to/file

dfn

用語定義

:dfn:`用語`

用語

危険

単語を強調するために、「」や ""、太字や斜体は使用してはなりません。
上記の単語表現の中から適切な記述を選んでください。

2.7. 画像

2.7.1. 画像(通常利用)

画像を本文中に挿入するためには figure を利用します。
画像は左寄せ表示を基本とします。

記載方法

下記のように記述します。

記述例

| 幅100pxで表示されます。

.. figure:: ../../../images/manual_design/charg.png
   :width: 100px
   :alt: role_of_index

   「幅100px」の画像 <--- キャプション

表示結果

幅100pxで表示されます。
role_of_index

図 2.78 「幅100px」の画像

注釈

バージョンアップ時に画像ファイルを更新する際は、以下のようにファイル名にバージョンを付けて新たな画像ファイルを用意してください。

元のファイル名: sample.png
新規ファイル名: sample_v2-3.png

2.7.2. 画像(文中引用)

画像を1行中に挿入するためには image を利用します。

記載方法

下記のように記述します。

記述例

画像を文中　|aa| に挿入できます。

.. |aa| image:: ../../../images/manual_design/chart.png
   :width: 2.0em
   :alt: サンプルイメージ

表示結果

画像を文中　サンプルイメージ に挿入できます。

2.8. 表・テーブル

2.8.1. リストテーブル(推奨)

リスト形式を使った記述方法です。
表を記載する際の基本方針として、グリッドテーブル形式ではなくリストテーブル形式で表現できないかを検討するべきです。

危険

原則、読みやすさ、記述のしやすさの理由から表の記述にリストテーブルを使用してください。
後述のグリッドテーブルは自由度が高いものの

記載方法

リスト形式でテーブルヘッダーや各レコードを記述します。

記述例

.. list-table:: リストテーブルサンプル
   :widths: 10 10 20
   :header-rows: 1
   :align: left

   * - カラム1
     - カラム2
     - | カラム3
       | (複数行)
   * - レコード1
     - | フィールド(1,2)
     - | フィールド(1,3)
       | リストテーブルでは
       | １セル内に複数行入れることが
       | 容易にできます。
   * - レコード2
     - フィールド(2,2)
     - フィールド(2,3)

表示結果

表 2.110 リストテーブルサンプル

カラム1

カラム2
カラム3
(複数行)

レコード1
フィールド(1,2)
フィールド(1,3)
リストテーブルでは
１セル内に複数行入れることが
容易にできます。

レコード2

フィールド(2,2)

フィールド(2,3)

2.8.2. フィルター付きリストテーブル

リスト形式を使ったカラムにフィルターがついた表の記述方法です。

記載方法

リスト形式でテーブルヘッダーや各レコードを記述します。
クラスに filter-table を指定します。

記述例

.. list-table:: リストテーブルサンプル
   :widths: 10 10 20
   :header-rows: 1
   :align: left
   :class: filter-table

   * - カラム1
     - カラム2
     - | カラム3
       | (複数行)
   * - レコード1
     - | フィールド(1,2)
     - | フィールド(1,3)
       | リストテーブルでは
       | １セル内に複数行入れることが
       | 容易にできます。
   * - レコード2
     - フィールド(2,2)
     - フィールド(2,3)

表示結果

表 2.111 リストテーブルサンプル

カラム1

カラム2
カラム3
(複数行)

レコード1
フィールド(1,2)
フィールド(1,3)
リストテーブルでは
１セル内に複数行入れることが
容易にできます。

レコード2

フィールド(2,2)

フィールド(2,3)

2.8.3. グリッドテーブル(非推奨)

ASCII 文字で表を表現する記述方法です。
表の中にコードを記載するなどの複雑な表現が必要な場合のみ利用します。

危険

原則、読みやすさ、記述のしやすさの理由から表の記述にリストテーブルを使用してください。
後述のグリッドテーブルは自由度が高いものの

記述例

.. table:: グリッドテーブルサンプル

   +----------+-------+---------+
   | 見出1    | 見出2 | 見出3   |
   |          |       |         |
   +==========+=======+=========+
   | 内容1    | 内容2 | 内容3   |
   +----------+-------+---------+

表示結果

表 2.112 グリッドテーブルサンプル

見出1

見出2

見出3

内容1

内容2

内容3

グリッドテーブル内表記の注意点

1行の中で改行したい場合の表示崩れ対処
フィールド内の1行を表現したいが、長すぎるために改行したい場合は、\ (バックスラッシュ・円マーク) を記述することで、次の行と間を開けずに表示することができます。

  • 正しい記述例

    +-------
| 通信条\    --> "通信条件" とつなげて出力されます。
| 件
    フィールド内で改行する際に、同時に空白を入れる場合は、 \ (スペース+バックスラッシュ・円マーク)と記載します。
     | Exastro \                | --> "Exastro ITAのWebコンテンツへのアクセス"
 | ITAのWebコンテンツへの\  |
 | アクセス                 |
 |                          |
-+--------------------------+

  • 誤った記述例

    +-------
| 通信条    --> "通信条 件" と出力されます。
| 件

     | Exastro\                 | --> 文字列が崩れます。 (空白が行頭にきています。)
 |  ITAのWebコンテンツへの\ |
 | アクセス                 |
 |                          |
-+--------------------------+

表内での一覧表記

記述例
.. table:: 表組例1

   +-----------------+---------+
   | 新機\           | 項目B   |
   | 能について      |         |   --> "*" 又は "#." を使って項目を列挙します。
   |                 |         |   --> 前行との間に要空白
   | * 項目1         |         |
   | * 項目2         |         |
   +-----------------+---------+

CSVテーブル(使用禁止)

CSV形式で表を表現する記述方法です。
フィールド内での改行を利用する場合などで上記の2つの記述方法に比べ見づらいため、使用は禁止とします。

記述例

.. csv-table:: CSVテーブルサンプル
   :header: 項目名1, 項目名2, 項目名3
   :widths: 10, 30, 30

   内容1, 内容2, 内容3

表示結果

表 2.113 CSVテーブルサンプル

項目名1

項目名2

項目名3

内容1

内容2

内容3

2.9. メモ

ユーザーが確認すべき内容ごとにレベルが分けをしたメモを記載している箇所がいくつかあります。
Note や Tip については読み飛ばしてもそれほど運用に影響はありませんが、Warning や Danger は運用上注意が必要な項目となりますので、ユーザーが確認することを推奨します。
吹き出し形式のメモには下記の意味があります。

2.9.1. 説明

記載方法

情報の重要度に応じて適切なレベルを選択してください。
レベルは Note` から Danger まで全部で4レベルあります。
各レベルの説明について下記を参照してください。

記述例

# Note
.. note::
   | 補足的な情報を示しています。
   | Note に記載されている内容は読み飛ばしても困ることは無いでしょう。

# Tip
.. tip::
   | 操作や作業におけるノウハウを示しています。
   | Tip に記載されている内容を読み飛ばした場合ユーザーに混乱が生じる可能性があります。

# Warning
.. warning::
   | 操作上の注意点を示しています。
   | Warning に記載された内容はユーザーが把握しておくほうが適切な情報です。

# Danger
.. danger::
   | 正常なサービスへ影響を与える可能性がある操作についての危険性を示しています。
   | Danger に記載された内容を知らない場合、大きな問題を引き起こす可能性があります。

表示結果

注釈

補足的な情報を示しています。
Note に記載されている内容は読み飛ばしても困ることは無いでしょう。

Tip

操作や作業におけるノウハウを示しています。
Tip に記載されている内容を読み飛ばした場合ユーザーに混乱が生じる可能性があります。

警告

操作上の注意点を示しています。
Warning に記載された内容はユーザーが把握しておくほうが適切な情報です。

危険

正常なサービスへ影響を与える可能性がある操作についての危険性を示しています。
Danger に記載された内容を知らない場合、大きな問題を引き起こす可能性があります。

2.10. リスト・箇条書き

2.10.1. 番号なしリスト

シンプルな箇条書きをします。

記載方法

箇条書きは文頭に - (ハイフン+スペース)を記載することで箇条書きになります。

警告

親リストと子リストの間は1行空ける必要があります。

記述例

- 項目1
- 項目2

  - 項目2-1
  - 項目2-2
- | 項目3
  | (複数行)

  - | 項目3-1
  - | 項目3-2
    | 複数行書くこともできます。

表示結果

  • 項目1

  • 項目2

    • 項目2-1

    • 項目2-2

  • 項目3
    (複数行)
    • 項目3-1
    • 項目3-2
      複数行書くこともできます。

2.10.2. 番号付きリスト

数字付きの箇条書きをします。

記載方法

箇条書きは文頭に #. (シャープor数字+ドット+スペース)を記載することで番号付き箇条書きになります。
親子関係がある場合には、末端の子供以外はすべて数字で記載する必要があります。

警告

親リストと子リストの間は1行空ける必要があります。

記述例

1. 項目1
2. 項目2

   #. 項目2-1
   #. 項目2-2
3. | 項目3
   | (複数行)

   # | 項目3-1
   # | 項目3-2
     | 複数行書くこともできます。

表示結果

  1. 項目1

  2. 項目2

    1. 項目2-1

    2. 項目2-2

  3. 項目3
    (複数行)
    1. 項目3-1
    2. 項目3-2
      複数行書くこともできます。

2.11. リスト・箇条書き (特殊系)

以下の方法では、装飾付きのリスト・箇条書きの方法を説明します。

2.11.1. 番号なしリスト (特殊系)

シンプルな箇条書き(特殊系)をします。

記載方法

箇条書きは文頭に - (ハイフン+スペース)を記載することで箇条書きになります。
項目を複数行で書いたり、次の行にインデントを入れると通常の箇条書きになります。

記述例

- 項目1

| パラグラフ1

- 項目2

| パラグラフ2

- | 項目3
  | 複数行記載すると通常の箇条書きになります。

- 項目4

  次の行にインデントがあると通常の箇条書きになります。

表示結果

  • 項目1

パラグラフ1

  • 項目2

パラグラフ2
  • 項目3
    複数行記載すると通常の箇条書きになります。

  • 項目4

    次の行にインデントがあると通常の箇条書きになります。

2.11.2. 番号付きリスト (特殊系)

数字付きの箇条書き(特殊系)をします。

記載方法

箇条書きは文頭に N. (数字+ドット+スペース)を記載することで番号付き箇条書き(特殊系)になります。
項目を複数行で書いたり、次の行にインデントを入れると通常の箇条書きになります。

記述例

1. 項目1

| パラグラフ1

2. 項目2

| パラグラフ2

3. | 項目3
   | 複数行記載すると通常の番号付き箇条書きになります。

4. 項目4

   次の行にインデントがあると通常の番号付き箇条書きになります。

表示結果

  1. 項目1

パラグラフ1

  1. 項目2

パラグラフ2
  1. 項目3
    複数行記載すると通常の番号付き箇条書きになります。

  2. 項目4

    次の行にインデントがあると通常の番号付き箇条書きになります。

2.11.3. 参照先のリンク表現

参照先のタイトル変更に伴う、修正等の運用観点から、タイトルの指定は、基本的に禁止とします。
OK：:doc:`参照先`
OK：:ref:`参照先`
NG：:doc:`title<参照先>`
NG：:ref:`title<参照先>`

注釈

OK： 「Ansible ドライバ」
NG： 「Ansibleドライバのマニュアルはこちら 」
OK： 「コード」
NG： 「コードについての参照先はこちらです。」
例外として、外部ページのリンクを参照する場合は、例外的に使用可能とします。
参照先
`title <参照先>`
# 例
OK： Sphinx日本語マニュアルは https://www.sphinx-doc.org/ja/master/ です。
OK： `Sphinx日本語マニュアル <https://www.sphinx-doc.org/ja/master/>`_
OK： Sphinx日本語マニュアルは `こちら <https://www.sphinx-doc.org/ja/master/>`_ です。

注釈

OK： Sphinx日本語マニュアルは https://www.sphinx-doc.org/ja/master/ です。
OK： Sphinx日本語マニュアル
OK： Sphinx日本語マニュアルは こちら です。

2.12. 禁止表現

2.12.1. H6 (見出し6) 以上の表現

H6レベルの見出しを表現する書式です。
H6レベル以上の見出し(H6を含む)は使ってはなりません。
通常、H6レベル以上の見出しになる場合は、文章の構造が複雑過ぎています。
書き方を工夫するなどしてH6レベル以上を使わないようにしなければなりません。

強調(イタリック、太字)

下記に記載する、太字や斜体は使用してはなりません。
適切な コード を選択してください。
*使用禁止(イタリック)*
**使用禁止(太字)**

使用禁止(イタリック) 使用禁止(太字)

CSVテーブル

CSV形式で表を表現する記述方法です。
フィールド内での改行を利用する場合などで上記の2つの記述方法に比べ見づらいため、使用は禁止とします。