相邻的 YAML 文档文件

插件的 YAML 文档

对于大多数 Ansible 插件，文档与代码位于同一个文件中。但在以下情况下，这种方法并不适用：

• 同一个文件中定义了多个插件，例如测试（tests）和过滤器（filters）。

• 插件是用 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 始终建议将文档与代码放在同一个文件中。

另请参阅

集合索引

浏览现有的集合、模块和插件

Python API

了解用于任务执行的 Python API

开发动态主机清单

了解如何开发动态清单源

开发模块

了解如何编写 Ansible 模块

交流方式

有疑问？需要帮助？想分享你的想法？请访问 Ansible 通信指南