相邻的 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 始终建议在大多数情况下将文档与代码放在同一个文件中。

另请参阅

集合索引

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

Python API

了解有关任务执行的 Python API 的信息

开发动态清单

了解如何开发动态清单源

开发模块

了解如何编写 Ansible 模块

沟通

有问题吗？需要帮助？想分享您的想法？请访问 Ansible 沟通指南