ドキュメントチートシート#

ドキュメントファイルには、MarkdownとMySTの構文が混在しています。

シンタックスのヘルプと規約については、以下のセクションを参照してください。

見出し#

入力

説明

#Title (タイトル)

ページのタイトルとH1の見出し

## ヘディング (見出し)

H2の見出し

### ヘディング (見出し)

H3の見出し

#### 見出し のようになります。

H4の見出し

...

その他の見出し

以下の規則に従ってください。

  • 間にテキストを挟まずに連続した見出しを使用しない。

  • 見出しには文型を使用する（最初の単語だけを大文字にする）。

  • レベルを飛ばさない（例えば、H2の後にはH4ではなく必ずH3をつける）。

インラインフォーマット#

入力

出力

{guilabel}`UI要素`

UI要素

`コード`

コード

{command}`コマンド`

コマンド

*Italic*

*イタリック

**Bold** (太字)

ボールド

以下の規則に従ってください。

  • イタリック体は控えめに使用してください。一般的にイタリック体を使うのは、タイトルや名前です（例えば、リンクできないセクションのタイトルを参照する場合や、コンセプトの名前を紹介する場合など）。

  • 太字は控えめに使いましょう。太字の一般的な使用方法は、UI要素です（「OKをクリックしてください」）。強調のために太字を使うことは避け、むしろ言いたいことが伝わるように文章を書き換えましょう。

コードブロック#

コードブロックの開始と終了は3つのバックティックで行います。

```

バックティックの後にコード言語を指定して、特定のレキサーを強制することもできますが、多くの場合、デフォルトのレキサーで十分に機能します。

入力

出力

 

```
# コードブロックのデモ
コードを表示します。
- 例：真
```


# コードブロックのデモ
コードを表示します。
- 例：真

``yaml
# コードブロックのデモ
コードを表示します。
- 例：真
```


# コードブロックのデモ
コードを表示します。
- 例：真

コードブロックにバックティックを含めるには、周囲のバックティックの数を増やします。

入力

出力

 

````
```
````



```

リンク#

リンクの方法は、外部のURLにリンクするのか、ドキュメントの他のページにリンクするのかによって異なります。

外部リンク#

外部リンクの場合、URLのみを使用し、リンクテキストを上書きしたい場合はMarkdownの構文を使用します。

入力

出力

https://linuxcontainers.org

https://linuxcontainers.org

[Linux コンテナ](https://linuxcontainers.org)

Linux コンテナ

URL をテキストとして表示し、リンクされないようにするには、<span></span> を追加します。

入力

出力

https:/<span></span>/linuxcontainers.org (日本語)

https:/<span></span>/linuxcontainers.org

内部参照#

内部参照の場合、Markdown と MyST の両方の構文がサポートされています。リンクテキストを自動的に解決し、GitHubのレンダリングでリンクを示すことができるので、ほとんどの場合、MyST構文を使用するべきです。

ページの参照#

ドキュメントのページを参照するには、MyST 構文を使ってリンクテキストを自動的に抽出します。リンクテキストを上書きする場合は、Markdownの構文を使用します。

入力

出力

GitHubでの出力

ステータス

{doc}`index`

LXD

{doc}index

望ましいのは

[](index)

LXD

使用しないでください。

[LXDドキュメント](index)

LXDドキュメント

LXDドキュメント

リンクテキストをオーバーライドするときに好ましい。

{doc}`LXD documentation <index>`

LXDドキュメント

{doc}LXD ドキュメント <index> {doc}LXD ドキュメント <index>

リンクテキストをオーバーライドする場合の代替手段

以下の規則に従ってください。

  • リンクテキストを上書きするのは、必要なときだけにしてください。ドキュメントのタイトルをリンクテキストとして使用できる場合は、そうしてください。なぜなら、タイトルが変更された場合、テキストは自動的に更新されるからです。

  • リンクテキストを、自動生成されるテキストと同じもので「上書き」してはいけません。

セクションの参照#

ドキュメント内のセクション（同じページまたは別のページ）を参照するには、セクションにターゲットを追加してそのターゲットを参照するか、自動生成されたアンカーとファイル名を組み合わせて使用します。

以下のような規約を守ってください。

  • セクションの中心的な部分や、頻繁にリンクされることが予想される「典型的な」場所にターゲットを追加してください。一度きりのリンクには、自動生成されるアンカーを使用できます。

  • 必要な場合のみリンクテキストを上書きする。セクションのタイトルをリンクテキストとして使用できる場合は、そうしてください。タイトルが変更された場合、テキストは自動的に更新されます。

  • リンクテキストを、自動生成されるテキストと同じもので「上書き」してはいけません。

ターゲットの使用#

ドキュメント内の任意の場所にターゲットを追加することができます。ただし、対象となる要素に見出しやタイトルがない場合は、リンクテキストを指定する必要があります。

入力

出力

GitHubでの出力

説明

(target_ID)=

(target_ID)=

ターゲットである target_ID を追加します。

{ref}`a_section_target` を追加します。

a_section_target {ref}a_section_target`

a_section_target `` {ref}a_section_target`

タイトルを持っているターゲットを参照します。

{ref}`リンクテキスト <a_random_target>`

リンクテキスト

{ref}リンクテキスト <a_random_target>

ターゲットを参照して、タイトルを指定します。

[`option name\](a_random_target)

option name

option name (リンク切れ)

リンクテキストをマークアプする必要がある場合は Markdown の文法を使ってください。
自動生成アンカーの使用#

自動生成されたアンカーを使用するには、Markdownの構文を使用する必要があります。 同じファイル内でリンクする場合は、ファイル名を省略できます。

入力

出力

GitHubでの出力

説明

[](#セクションの参照)

セクションの参照

使用しないでください。

[リンクテキスト](#セクションの参照)

リンクテキスト

リンクテキスト

リンクテキストをオーバーライドする場合に好ましい。

ナビゲーション#

すべてのドキュメントページは、ナビゲーションの中の他のページのサブページとして含まれていなければなりません。

これは、親ページのtoctreeディレクティブで実現します。 

```{toctree}
:hidden:

サブページ1
subpage1
subpage2
```

ナビゲーションに含めてはいけないページがある場合、ファイルの先頭に次のような命令を記述することで、結果として生じるビルド警告を抑制することができます。

---
orphan: true
---

孤児ページを使うのは、明確な理由がある場合に限られます。

リスト#

入力

出力

 
- 項目1
- 項目2
- 項目3

項目1

  • 項目2

  • 項目3

 
1. ステップ1
1. ステップ2
1. ステップ3

  1. ステップ1

  2. ステップ2

  3. ステップ3

 
1. ステップ1
   - アイテム1
     * 小項目
   - 項目2
1. ステップ2
   1. サブステップ1
   1. サブステップ2

1.ステップ1

  • 項目1

    • 小項目

  • 項目2

  1. ステップ2

    1. サブステップ1

    2. サブステップ2

以下の規則に従ってください。

  • 番号付きリストでは、ステップ番号を自動的に生成するために、すべての項目に 1. を使用してください。

  • 順不同のリストには-を使用してください。入れ子のリストを使用する場合は、入れ子のレベルに * を使用します。

定義リスト#

入力

出力

 
項番
: 定義

用語2
: 定義
用語1

定義

用語2

定義

テーブル#

標準的なMarkdownのテーブルを使用することができます。しかし、rST list tableの構文を使用する方が通常ははるかに簡単です。

どちらのマークアップも以下のような出力になります。

ヘッダ1

ヘッダー2

セル1

第2段落 セル1

セル2

セル3

セル4

マークダウンテーブル#

| Header 1                           | Header 2 |
|------------------------------------|----------|
| Cell 1<br><br>2nd paragraph cell 1 | Cell 2   |
| Cell 3                             | Cell 4   |

リストテーブル#

```{list-table}
   :header-rows: 1

* - Header 1
  - Header 2
* - Cell 1

    2nd paragraph cell 1
  - Cell 2
* - Cell 3
  - Cell 4
```

ノート#

入力

出力

 
```{note}
A note.
```

注釈

A note.

 
```{tip}
A tip.
```

Tip

A tip.

 
```{important}
Important information
```

重要

Important information.

 
```{caution}
This might damage your hardware!
```

注意

This might damage your hardware!

以下の規則に従ってください。

  • メモの使用は控えめに。

  • 以下のタイプのノートのみを使用してください。note, tip, important, caution` です。

  • caution は、ハードウェアの破損やデータの損失の危険性が明らかな場合にのみ使用してください。

画像#

入力

出力

 
![Altテキスト](https://linuxcontainers.org/static/img/containers.png)

Altテキスト

 
```{figure} https://linuxcontainers.org/static/img/containers.png
   :width: 100px
   :alt: Altテキスト

   図のキャプション
```
Altテキスト

図のキャプション#

以下のような規約があります。

  • doc ディレクトリ内の画像は、パスを / で始めてください (例: /images/image.png)。

  • スクリーンショットはPNG形式、グラフィックはSVG形式を使用してください。

代用#

あまり多くのマークアップや特殊なフォーマットをせずに文や段落を再利用するには、置換を使用します。

置換機能は以下の場所で定義できます。

  • substitutions.yaml というファイルがあります。このファイルで定義された置換は、すべてのドキュメントページで利用できます。

  • 次のような形式の単一のファイルの先頭に。

    ---
myst:
  substitutions:
    reuse_key: "これは **インクルードされた** テキストです"
    advanced_reuse_key: "これはコードブロックを含む置換文です。
                         ```
                         コードブロック
                         ```"
---

reuse/substitutions.py でデフォルトの置換を定義し、ファイルの先頭でそれをオーバーライドすることで、両方のオプションを組み合わせることができます。

入力

出力

{{reuse_key}}

これは インクルードされた テキストです

{{advanced_reuse_key}}

これはコードブロックを含む置換文です。 コードブロック

以下の規約に従ってください。

  • 置換はGitHubでは機能しません。そのため、インクルードされたテキストを示すキー名を使用してください (例えば、reuse_note の代わりに note_not_supported とします)。

ファイルのインクルード#

長いセクションや高度なマークアップを施したテキストを再利用するには、コンテンツを別のファイルに置き、そのファイルまたはファイルの一部を複数の場所にインクルードすることができます。

再利用するコンテンツにターゲットを入れることはできません (このターゲットへの参照が曖昧になるため)。ただし、ファイルをインクルードする直前にターゲットを置くことはできます。

ファイルのインクルードと置換を組み合わせれば、インクルードされたテキストの一部を置き換えることもできます。

入力

出力

 

% Include parts of the content from file [../README.md](../README.md)
```{include} ../README.md
   :start-after: パッケージからのLXDのインストール
   :end-before: <!-- Include end installing -->
```

LXDのデーモンはLinuxでしか動作しませんが、クライアントツール(lxc)はほとんどのプラットフォームで利用可能です。

OS

フォーマット

コマンド

Linux

Snap

snap install lxd

Windows

Chocolatey

choco install lxc

MacOS

Homebrew

brew install lxc

様々なLinuxディストリビューションやOSへのLXDのインストールについては、私たちのウェブサイトに詳しい説明があります。

以下の規則に従ってください。

  • ファイルのインクルードはGitHubでは機能しません。そのため、必ずインクルードしたファイルにリンクするコメントを追加してください。

  • テキストの一部を選択するには、開始点と終了点にHTMLコメントを追加し、可能であれば :start-after: と :end-before: を使用します。必要に応じて、:start-after:と:end-before:を:start-line:と:end-line:と組み合わせることができます。ただし:start-line:と:end-line:だけの使用はエラーになりやすいです。

タブ#

入力

出力

 

````{tabs}

```{group-tab} Tab 1

Content Tab 1
```

```{group-tab} Tab 2

Content Tab 2
```

````

Content Tab 1

折りたたみ可能なセクション#

rSTには詳細セクションのサポートはありませんが、HTMLを挿入してセクションを作成することができます。

入力

出力

 
<details>
<summary>Details</summary>

Content
</details>
Details

Content

用語集#

用語集はどのファイルでも定義することができます。理想的には、すべての用語を1つの用語集ファイルにまとめ、どのファイルからでも参照できるようにすることです。

入力

出力

 

```{glossary}

example term
  Definition of the example term.
```
example term#

Definition of the example term.

{term}`example term`

example term

さらに便利なマークアップ#

Input

Output

 

```{versionadded} X.Y
```

バージョン X.Y で追加.

{abbr}`API (Application Programming Interface)`

API

カスタムの拡張#

このドキュメントではいくつかのカスタム拡張を使っています。

関連リンク#

ページの先頭に以下のフィールドを追加することでサイドバーに関連するウェブサイトへのリンクを追加できます。

relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)

タイトルをオーバーライドするには、マークダウン文法を使います。空白は無視されることに注意してください。タイトル内に空白が必要な場合、&#32;に置き換えてください。メタデータの値が[で始まる場合にSphinxが文句を言う場合は値をクォートで囲んでください。

Discourseのトピックへのリンクを追加するには、頁の先頭に以下のフィールドを追加してください(12345はDiscourseのトピックIDです):

discourse: 12345

YouTubeのリンク#

YouTube動画へのリンクを追加するには、以下のように指定します:

Input

Output

 

```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0
:title: Demo
```

▶ Watch on YouTube

動画のタイトルは自動で抽出され、リンクにホバーした際に表示されます。 タイトルをオーバーライドするには:title:オプションを追加してください。

スペルの例外#

スペルの慣習に沿わないけれど、とあるコンテキストでは正しい単語を使う必要がある場合、{spellexception}で囲むことでスペルチェッカーから免除できます。

Input

Output

{spellexception}`PurposelyWrong`

PurposelyWrong

ターミナル出力#

コマンドと出力のターミナルの表示を示すには、以下のようにします:

Input

Output

 

```{terminal}
:input: command number one
:user: root
:host: vm

output line one
output line two
:input: another command
more output
```
root@vm:~# command number one
output line oneoutput line two
root@vm:~# another command
more output

入力は:input:オプションで指定します(あるいはメインの内容の一部で:input:という接頭辞を付けます)。 出力はメインの内容で指定します。

プロンプト(デフォルトではuser@host:~$)をオーバーライドする場合、:user:や:host:を指定します。 長い行をラップする代わりにターミナルを水平スクロールすうには:scroll:を追加します。