相邻 YAML 文档文件
插件的 YAML 文档
对于大多数 Ansible 插件，文档都与代码位于同一个文件中。这种方法不适用于以下情况：
同一个文件中定义了多个插件，例如测试和过滤器。
插件使用 Python（模块）以外的语言编写。
这些情况需要插件在相邻的 .py 文件中提供文档。从 ansible-core 2.14 开始，您可以将文档提供为相邻的 YAML 文件。YAML 文档文件的格式与其 Python 等效文件几乎相同，只是它是纯 YAML。
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 始终建议在大多数情况下将文档与代码放在同一个文件中。