隣接 YAML ドキュメントファイル

プラグインの YAML ドキュメント

ほとんどの Ansible プラグインでは、ドキュメントはコードと同じファイルにあります。このアプローチは、次の場合には機能しません。

• テストやフィルターなど、複数のプラグインが同じファイルで定義されている場合。

• プラグインが Python 以外の言語 (モジュール) で記述されている場合。

このような場合、隣接する .py ファイルでドキュメントを提供するプラグインが必要です。ansible-core 2.14 以降では、代わりに隣接 YAML ファイルとしてドキュメントを提供できます。YAML ドキュメントファイルの形式は、純粋な YAML であることを除いて Python の該当ファイルとほぼ同じです。

YAML 形式

Python では、各セクションは変数 DOCUMENTATION = r""" ... """ ですが、YAML ではマッピングキー DOCUMENTATION: ... です。

これは、ドキュメントが Python ファイルに埋め込まれていることを示す長い例です。

DOCUMENTATION = r'''
  description: something
  options:
    option_name:
      description: describe this config option
      default: default value for this config option
      env:
        - name: NAME_OF_ENV_VAR
      ini:
        - section: section_of_ansible.cfg_where_this_config_option_is_defined
          key: key_used_in_ansible.cfg
      vars:
        - name: name_of_ansible_var
        - name: name_of_second_var
          version_added: X.x
      required: True/False
      type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath
      version_added: X.x
'''

EXAMPLES = r'''
  # TODO: write examples
'''

次の例は、同じドキュメントを YAML 形式で示しています。

DOCUMENTATION:
  description: something
  options:
    option_name:
      description: describe this config option
      default: default value for this config option
      env:
        - name: NAME_OF_ENV_VAR
      ini:
        - section: section_of_ansible.cfg_where_this_config_option_is_defined
          key: key_used_in_ansible.cfg
      vars:
        - name: name_of_ansible_var
        - name: name_of_second_var
          version_added: X.x
      required: True/False
      type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath
      version_added: X.x

EXAMPLES: # TODO: write examples

上記の例が示すように、Python 変数にはすでに YAML が含まれています。YAML ドキュメントを使用するための主な変更点として、そのような変数から YAML を移動させます。

隣接 YAML ドキュメントファイルは、ドキュメント化するプラグインまたはモジュールと同じディレクトリーにある必要があります。これは、プラグインまたはモジュールを含む任意のディレクトリーでドキュメントを利用できることを意味します。

サポート対象のプラグインタイプ

YAML ドキュメントは、主にフィルター、テスト、モジュールを対象としています。他のプラグインタイプで使用できますが、Ansible では可能な限りコードと同じファイルにドキュメントを含めることが推奨されます。