相邻的 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 通信指南