Ansible スタイルガイド¶

Ansible スタイルガイドにようこそ! docs.ansible.com に、明確および簡潔で、一貫性のある有用なドキュメントを作成するために、以下のガイドラインが指定されています。

言語のガイドライン
reStructuredText のガイドライン
- ヘッダーの表記法
- 内部ナビゲーション
参考資料

言語のガイドライン ¶

Ansible ドキュメントでは、以下を目標にしています。

明確な
直接的な
会話的な
翻訳が容易な

Ansible が提供するドキュメントは、経験豊富で友好的な同僚に Ansible の仕組みを説明してもらっていると感じられるようなものにすることを目標にしています。

文体の早見表 ¶

以下の早見表は、「Ansibleのトーン」を実現するのに役立つルールを示しています。

ヘッダーの書式 ¶

ヘッダーは文で使用される書式で記述する必要があります。たとえば、このセクションのタイトルは、「Header case」とします (Header Case や HEADER CASE にはしません)。

ラテン語のフレーズを使用しない ¶

e.g. や etc. などのラテン語およびフレーズは、英語話者であれば簡単に理解できます。ただし、その他の人にとっては理解が難しい場合もあり、自動翻訳の際にも注意が必要になります。

したがって、ラテン語の用語または略語の代わりに、英語の用語を使用します。

ラテン語 \| 英語
i.e	in other words
e.g.	for example
etc	and so on
via	by/ through
vs./versus	rather than/against

reStructuredText のガイドライン ¶

Ansible ドキュメントは reStructuredText で記述され、Sphinx によって処理されます。すべての rST ページに対して、以下の技術的または機械的なガイドラインが指定されています。

ヘッダーの表記法 ¶

Section headers in reStructuredText は、さまざまな表記を使用できます。 Sphinx は、ヘッダーの階層を作成するときに「オンザフライで学習」します。ドキュメントを読みやすく、編集できるようにするために、標準のヘッダー表記法に従います。以下を使用します。

### 上線付き (各部分の場合)

###############
Developer guide
###############

*** 上線付き (章の場合)

*******************
Ansible スタイルガイド
*******************

=== セクションの場合

Mechanical guidelines
=====================

--- サブセクションの場合

Internal navigation
-------------------

^^ サブサブセクションの場合

Adding anchors
^^^^^^^^^^^^^^

""" パラグラフの場合

Paragraph that needs a title
""""""""""""""""""""""""""""

アンカー (ラベルとも呼ばれます) およびリンクは、ユーザーが関連コンテンツを見つけるのに役立つように機能します。また、ページ内の目次は、必要な情報にすばやく移動するのに役立ちます。内部リンクはすべて :ref: 構文を使用する必要があります。すべてのページには、内部の :ref: リンクをサポートするアンカーが少なくとも 1 つ必要です。長いページ、または複数レベルのヘッダーを持つページには、ページ内の目次を追加できます。

アンカーの追加 ¶

すべてのページに少なくとも 1 つのアンカーを含める。
メインヘッダーの上にメインアンカーを配置する。
このファイルに一意のタイトルがある場合は、メインページのアンカーに使用する。
ページにアンカーを追加することもできます。

内部リンクの追加 ¶

すべての内部リンクには :ref: 構文を使用する必要があります。これらのリンクは共に、上で定義したアンカーを指定します。

:ref:`unique_page`
:ref:`this page <unique_page>`

2 つ目の例は、リンクのカスタムテキストを追加します。

モジュールおよびプラグインへのリンクの追加 ¶

モジュールリンクはモジュール名に続けて、アンカーに _module を使用します。
プラグインリンクは、プラグイン名に続けてプラグインタイプを使用します。たとえば、enable become plugin を使用します。

:ref:`this module <this_module>``
:ref:`that connection plugin <that_connection>`

ページ内目次の追加 ¶

本ページには、ページ内目次が含まれています。ページ内目次を追加する場合は、以下のようにします。

目次の下に、主要な見出しと (任意で) 紹介文を追加する。
そのページの主要なヘッダーが含まれないように :local: ディレクティブを使用する。
タイトルは除外する。

構文は以下のようになります。

.. contents::
   :local:

参考資料 ¶

以下のページでは、ドキュメントに関する文法、スタイル、および技術的なルールを紹介しています。