模块格式和文档

如果您想将您的模块贡献给大多数 Ansible 集合，您必须使用 Python 编写模块并遵循下面描述的标准格式。（除非您正在编写 Windows 模块，在这种情况下，应适用Windows 指南。）除了遵循此格式之外，您还应该在打开拉取请求之前查看我们的提交清单、编程技巧和维护 Python 2 和 Python 3 兼容性的策略，以及有关测试的信息。

每个用 Python 编写的 Ansible 模块都必须以特定顺序以七个标准部分开头，然后是代码。这些部分按顺序排列如下：

注意

为什么导入语句不在最前面？

敏锐的 Python 程序员可能会注意到，与 PEP 8 的建议相反，我们没有将imports放在文件的顶部。这是因为DOCUMENTATION到RETURN部分没有被模块代码本身使用；它们本质上是文件的额外文档字符串。出于与 PEP 8 将导入语句放在介绍性注释和文档字符串之后相同的原因，导入语句放置在这些特殊变量之后。这样可以将代码的活动部分放在一起，并将纯信息部分分开。排除 E402 的决定是基于可读性（这就是 PEP 8 的目的）。模块中的文档字符串与模块级文档字符串更相似，而不是代码，并且从未被模块本身使用。将导入语句放在此文档下方并更靠近代码，可以以一致的方式合并和分组所有相关的代码，以提高可读性、调试和理解。

警告

小心复制旧模块！

一些较旧的 Ansible 模块在文件底部有imports，带有完整 GPL 前缀的Copyright声明，和/或顺序错误的DOCUMENTATION字段。这些是需要更新的旧文件 - 不要将它们复制到新模块中。随着时间的推移，我们正在更新和纠正旧模块。请遵循此页面上的指南！

注意

对于非 Python 模块，您仍然可以为文档目的创建一个.py文件。从 ansible-core 2.14 开始，您可以选择创建一个.yml文件，该文件具有相同的数据结构，但使用纯 YAML。对于 YAML 文件，下面的示例很容易使用，方法是删除 Python 引号并将=替换为:，例如DOCUMENTATION = r''' ... '''到DOCUMENTATION: ...并删除结束引号。相邻的 YAML 文档文件

Python Shebang 和 UTF-8 编码 

以#!/usr/bin/python开头您的 Ansible 模块 - 此“Shebang”允许ansible_python_interpreter工作。紧跟在 Shebang 之后的是# -*- coding: utf-8 -*-，以阐明该文件采用 UTF-8 编码。

警告

使用#!/usr/bin/env会使env成为解释器，并绕过ansible_<interpreter>_interpreter逻辑。
在 Shebang 中传递参数给解释器不起作用（例如，#!/usr/bin/env python）。

注意

如果您使用不同的脚本语言开发模块，请相应地调整解释器（#!/usr/bin/<interpreter>），以便ansible_<interpreter>_interpreter可以为此特定语言工作。

注意

二进制模块不需要 Shebang 或解释器。

版权和许可证 

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: Contributors to the Ansible project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

# Copyright: Contributors to the Ansible project

ANSIBLE_METADATA 块 

自从我们迁移到集合以来，我们已经弃用了 METADATA 功能，它不再是模块所必需的，但如果存在，也不会破坏任何东西。

DOCUMENTATION 块 

在 Shebang、UTF-8 编码、版权声明行和许可证部分之后是DOCUMENTATION块。Ansible 的在线模块文档是从每个模块源代码中的DOCUMENTATION块生成的。DOCUMENTATION块必须是有效的 YAML。您可能会发现，在将其包含在 Python 文件中之前，首先使用具有 YAML 语法高亮的编辑器编写DOCUMENTATION字符串更容易一些。您可以从将我们的示例文档字符串复制到您的模块文件中并进行修改开始。如果您在 YAML 中遇到语法问题，您可以在YAML Lint网站上对其进行验证。

模块文档应简短而准确地定义每个模块和选项的功能，以及它与底层系统中其他模块的协同工作方式。文档应为广泛的受众编写——专家和非专家都能阅读。

描述应始终以大写字母开头，并以句号结尾。一致性始终会有所帮助。
验证 doc 和模块规范字典中的参数是否相同。
对于密码/秘密参数，应设置no_log=True。
对于似乎包含敏感信息但**不**包含秘密的参数，例如“password_length”，请设置no_log=False以禁用警告消息。
如果某个选项仅在某些情况下是必需的，请描述这些条件。例如，“当 I(state=present) 时是必需的”。
如果您的模块允许check_mode，请在文档中反映这一事实。

要创建清晰、简洁、一致且有用的文档，请遵循样式指南。

下面将描述每个文档字段。在提交模块文档之前，请在命令行和 HTML 中对其进行测试。

只要您的模块文件在本地可用，您就可以使用ansible-doc -t module my_module_name在命令行中查看您的模块文档。任何解析错误都将很明显 - 您可以通过向命令添加-vvv来查看详细信息。
您还应该测试模块文档的 HTML 输出。

文档字段

DOCUMENTATION块中的所有字段都小写。除非另有说明，否则所有字段都是必需的。

module：

模块的名称。
必须与文件名相同，不包含.py扩展名。

short_description:

在资源集合索引页面和ansible-doc -l中显示的简短描述。
short_description由ansible-doc -l显示，不进行任何类别分组，因此它需要足够详细的信息来解释模块的用途，而无需其所在目录结构的上下文。
与description:不同，short_description不应该以句点结尾。

description:

详细描述（通常为两句或更多句）。
必须用完整的句子书写，也就是要使用大写字母和句点。
不应该提及模块名称。
应使用多个条目，而不是使用一个长段落。
除非YAML要求，否则不要引用完整的值。

version_added:

添加模块的Ansible版本。
这是一个字符串，而不是浮点数，例如version_added: '2.1'。
在集合中，这必须是模块添加到其中的集合版本，而不是Ansible版本。例如，version_added: 1.0.0。

author:

模块作者的姓名，格式为First Last (@GitHubID)。
如果有多个作者，请使用多行列表。
不要使用引号，因为YAML不需要。

deprecated:

标记将在未来版本中删除的模块。另请参见Ansible 模块或插件的生命周期。

options:

选项通常被称为“参数”或“参数”。因为文档字段被称为options，我们将使用该术语。
如果模块没有选项（例如，它是一个_facts模块），你只需要一行：options: {}。
如果你的模块有选项（换句话说，接受参数），则应详细记录每个选项。对于每个模块选项，请包含

option-name:

声明式操作（不是CRUD），关注最终状态，例如online:，而不是is_online:。
选项名称应与模块的其余部分以及同一类别中的其他模块保持一致。
如有疑问，请查找其他模块以查找用于相同目的的选项名称，我们希望为用户提供一致性。
（没有明确的字段option-name。此条目指的是options字典中选项的键。）

description:

此选项作用的详细说明。它应该用完整的句子书写。
第一个条目是对选项本身的描述；后续条目详细说明其用途、依赖项或可能值的格式。
不应列出可能的值（这就是choices:的用途，尽管如果值不明显，它应该解释这些值的作用）。
如果某个选项仅在某些情况下是必需的，请描述这些条件。例如，“当 I(state=present) 时是必需的”。
互斥选项必须作为每个选项的最后一句进行记录。

required:

只有在true时才需要。
如果缺少，我们假设该选项不是必需的。

default:

如果required为false/缺失，则可以指定default（如果缺失，则假定为“null”）。
确保文档中的默认值与代码中的默认值匹配。
除非需要其他信息或条件，否则不应将默认字段列为描述的一部分。
如果选项是布尔值，则可以使用Ansible识别的任何布尔值（例如true/false或yes/no）。为了与ansible-lint保持一致性和兼容性，将布尔值记录为true/false。

choices:

选项值的列表。
如果为空，则应不存在。

type:

指定选项接受的数据类型，必须与argspec匹配。
如果参数为type='bool'，则此字段应设置为type: bool，并且不应指定choices。
如果参数为type='list'，则应指定elements。

elements:

如果type='list'，则指定列表元素的数据类型。

aliases:

可选名称别名的列表。
通常不需要。

version_added:

仅当在初始Ansible版本发布后扩展此选项时才需要，换句话说，这大于顶级version_added字段。
这是一个字符串，而不是浮点数，例如version_added: '2.3'。
在集合中，这必须是添加选项的集合版本，而不是Ansible版本。例如，version_added: 1.0.0。

suboptions:

如果此选项采用字典或字典列表，则可以在此处定义结构。
请参阅azure.azcollection.azure_rm_securitygroup、azure.azcollection.azure_rm_azurefirewall和openstack.cloud.baremetal_node_action了解示例。

requirements:

需求列表（如果适用）。
包含最低版本。

seealso:

其他模块、文档或互联网资源的参考列表
在Ansible 2.10及更高版本中，对模块的引用必须使用FQCN或ansible.builtin用于ansible-core中的模块。
自ansible-core 2.15起支持插件引用。

引用可以采用以下格式之一

seealso:

# Reference by module name
- module: cisco.aci.aci_tenant

# Reference by module name, including description
- module: cisco.aci.aci_tenant
  description: ACI module to create tenants on a Cisco ACI fabric.

# Reference by plugin name
- plugin: ansible.builtin.file
  plugin_type: lookup

# Reference by plugin name, including description
- plugin: ansible.builtin.file
  plugin_type: lookup
  description: You can use the ansible.builtin.file lookup to read files on the control node.

# Reference by rST documentation anchor
- ref: aci_guide
  description: Detailed information on how to manage your ACI infrastructure using Ansible.

# Reference by rST documentation anchor (with custom title)
- ref: The official Ansible ACI guide <aci_guide>
  description: Detailed information on how to manage your ACI infrastructure using Ansible.

# Reference by Internet resource
- name: APIC Management Information Model reference
  description: Complete reference of the APIC object model.
  link: https://developer.cisco.com/docs/apic-mim-ref/

如果你使用ref:链接到与标题不相关的锚点，则必须为链接添加标题才能使其正常工作。

attributes:

一个字典，将属性名称映射到描述该属性的字典。
通常，属性由文档片段提供，例如ansible.builtin.action_common_attributes及其子片段。模块和插件使用适当的文档片段并填写support、details和潜在的特定于属性的其他字段。

description:

字符串或字符串列表。每个字符串是一个段落。描述是必需的。
此属性作用的说明。它应该用完整的句子书写。

details:

字符串或字符串列表。每个字符串是一个段落。
描述支持如何可能无法按用户预期工作。
细节通常是可选的，但如果support为partial，则必须提供。

support:

full、none、partial或N/A之一。这是必需的。
指示此模块或插件是否支持此属性。

membership:

字符串或字符串列表。
只能用于属性action_group，并且必须始终为该属性指定。
列出此模块或操作所属的操作组。

platforms:

字符串或字符串列表。
只能用于属性platform，并且必须始终为该属性指定。
列出模块或操作支持的平台。

version_added:

仅当在此模块/插件创建后扩展此属性的支持时才需要，换句话说，这大于顶级version_added字段。
这是一个字符串，而不是浮点数，例如version_added: '2.3'。
在集合中，这必须是添加属性支持的集合版本，而不是Ansible版本。例如，version_added: 1.0.0。

notes:

任何不适合上述部分的重要信息的详细信息。
关于check_mode或diff的信息**不**应列在此处，而应在attributes中提及。

模块文档内的链接

你可以使用一些预定义的宏，从你的模块文档链接到其他模块文档、docs.ansible.com上的其他资源以及互联网上的其他资源。这些宏的正确格式是

L()用于带有标题的链接。例如：See L(Ansible Automation Platform,https://ansible.org.cn/products/automation-platform). 从Ansible 2.10开始，不要将L()用于Ansible文档和集合文档之间的相对链接。
U()用于URL。例如：See U(https://ansible.org.cn/products/automation-platform) for an overview.
R()用于带有标题的交叉引用（在Ansible 2.10中添加）。例如：See R(Cisco IOS Platform Guide,ios_platform_options)。使用RST锚点进行交叉引用。有关详细信息，请参阅添加锚点。
模块名称使用M()。例如：See also M(ansible.builtin.yum) or M(community.general.apt_rpm)。必须使用全限定类名 (FQCN)，短名称会导致链接失效；对于 ansible-core 中的模块，请使用ansible.builtin。
插件名称使用P()。例如：See also P(ansible.builtin.file#lookup) or P(community.general.json_query#filter)。这也可以引用角色：P(community.sops.install#role)。ansible-core 2.15 及更高版本支持此功能。必须使用 FQCN；对于 ansible-core 中的插件，请使用ansible.builtin。

注意

对于集合内模块和文档之间的链接，可以使用上述任何选项。对于集合外的链接，如果可用，请使用R()。否则，请使用U() 或 L() 并提供完整的 URL（非相对链接）。对于模块，请使用带有 FQCN 或 ansible.builtin 的 M()，如示例所示。如果您正在创建自己的文档站点，则需要使用intersphinx 扩展将 R() 和 M() 转换为正确的链接。

注意

要引用集合中的一组模块，请使用R()。当集合的粒度不够细时，请使用C(..)。

有关管理 kubernetes 集群的信息，请参阅 R(kubernetes.core collection, plugins_in_kubernetes.core)。

C(win_*) 模块（分布在多个集合中）允许您管理 Windows 主机的各个方面。

注意

由于更醒目，请使用seealso 用于一般引用，而不是使用注释或在描述中添加链接。

模块文档中的语义标记

您可以使用语义标记来突出显示选项名称、选项值和环境变量。标记处理器以统一的方式格式化这些突出显示的术语。使用语义标记，我们可以修改输出的外观，而无需更改底层代码。

语义标记的正确格式如下所示

选项名称使用O()，无论单独提及还是与值一起提及。例如：Required if O(state=present). 和 Use with O(force) to require secure access.
单独提及的选项值使用V()。例如：Possible values include V(monospace) and V(pretty).
返回值名称使用RV()，无论单独提及还是与值一起提及。例如：The module returns RV(changed=true) in case of changes. 和 Use the RV(stdout) return value for standard output.
环境变量使用E()。例如：If not set, the environment variable E(ACME_PASSWORD) will be used.

这些格式化函数的参数可以使用反斜杠进行转义：V(foo(bar="a\\b"\), baz) 的格式化值为 foo(bar="a\b"), baz)。

使用O() 和 RV() 的规则非常严格。您必须遵循语法规则，以便文档渲染器可以分别为选项和返回值创建超链接。

允许的语法如下所示

要引用当前插件/模块的选项，或当前角色的入口点（在角色入口点文档内），请使用O(option) 和 O(option=name)。
要在角色文档内引用另一个入口点entrypoint 的选项，请使用O(entrypoint:option) 和 O(entrypoint:option=name)。文档渲染器可以忽略入口点信息，将其转换为指向该入口点的链接，甚至直接指向该入口点的选项。
要引用类型为type 的另一个插件/模块plugin.fqcn.name 的选项，请使用O(plugin.fqcn.name#type:option) 和 O(plugin.fqcn.name#type:option=name)。对于模块，请使用type=module。文档渲染器可以忽略 FQCN 和插件类型，将其转换为指向该插件的链接，甚至直接指向该插件的选项。
要引用另一个角色role.fqcn.name 的入口点entrypoint 的选项，请使用O(role.fqcn.name#role:entrypoint:option) 和 O(role.fqcn.name#role:entrypoint:option=name)。文档渲染器可以忽略 FQCN 和入口点信息，将其转换为指向该入口点的链接，甚至直接指向该入口点的选项。
要引用不存在的选项（例如，在早期版本中已删除的选项），请使用O(ignore:option) 和 O(ignore:option=name)。ignore: 部分不会显示给用户。

选项名称可以通过列出用点分隔的选项路径来引用子选项。例如，如果您有一个带有子选项bar 的选项foo，则必须使用O(foo.bar) 来引用该子选项。您可以添加数组指示，例如O(foo[].bar) 甚至O(foo[-1].bar) 来指示特定的列表元素。[ 和 ] 对之间的所有内容都将被忽略，以确定选项的实际名称。例如，O(foo[foo | length - 1].bar[]) 与O(foo.bar)的结果链接相同，但显示的文本为foo[foo | length - 1].bar[] 而不是 foo.bar。

相同的语法可用于RV()，只是这些将引用返回值名称而不是选项名称；例如RV(ansible.builtin.service_facts#module:ansible_facts.services) 指的是由ansible.builtin.service_facts 模块返回的ansible_facts.services 事实。

模块文档中的格式宏

虽然可以使用标准的 Ansible 格式化宏来控制模块文档中其他术语的外观，但应谨慎使用。

可能的宏包括以下内容

C() 用于monospace（代码）文本。例如：This module functions like the unix command C(foo).
B() 用于粗体文本。
I() 用于斜体文本。
HORIZONTALLINE 用于水平线（<hr> html 标签），用于分隔较长的描述。

请注意，C()、B() 和 I()**不允许转义**，因此不能包含值)，因为它总是结束格式化序列。如果您需要在C() 中使用)，我们建议改用V()；请参见上面关于语义标记的部分。

文档片段

如果您正在编写多个相关的模块，它们可能共享一些公共文档，例如身份验证细节、文件模式设置、notes: 或 seealso: 条目。与其在每个模块的 DOCUMENTATION 块中重复这些信息，不如将其一次性保存为 doc_fragment 插件，然后在每个模块的文档中使用它。在 Ansible 中，共享的文档片段包含在 lib/ansible/plugins/doc_fragments/ 或集合中的等效目录中的 ModuleDocFragment 类中。要包含文档片段，请在您的模块文档中添加 extends_documentation_fragment: FRAGMENT_NAME。对 FRAGMENT_NAME 使用完全限定的集合名称（例如，kubernetes.core.k8s_auth_options）。

只有当模块以与导入该片段的现有模块相同的方式实现其中记录的所有接口时，模块才应使用文档片段中的项目。目标是，从文档片段导入的项目在用于导入该文档片段的其他模块时，其行为应完全相同。

默认情况下，只有文档片段中的 DOCUMENTATION 属性会被插入到模块文档中。可以在文档片段中定义其他属性，以便只导入文档片段的某些部分，或者根据需要进行混合匹配。如果文档片段和模块中都定义了某个属性，则模块值将覆盖文档片段值。

这是一个名为 example_fragment.py 的文档片段示例

class ModuleDocFragment(object):
    # Standard documentation
    DOCUMENTATION = r'''
    options:
      # options here
    '''

    # Additional section
    OTHER = r'''
    options:
      # other options here
    '''

要在模块中插入 OTHER 的内容

extends_documentation_fragment: example_fragment.other

或者同时使用两者

extends_documentation_fragment:
  - example_fragment
  - example_fragment.other

2.8 版本新增。

从 Ansible 2.8 开始，您可以通过在 playbook 或角色旁边使用 doc_fragments 目录来使用用户提供的 doc_fragments，就像任何其他插件一样。

例如，所有 AWS 模块都应包含

extends_documentation_fragment:
- aws
- ec2

在集合中使用文档片段描述了如何在集合中包含文档片段。

EXAMPLES 块 

根据 playbook 最佳实践，每个示例都应包含 name: 行

EXAMPLES = r'''
- name: Ensure foo is installed
  namespace.collection.modulename:
    name: foo
    state: present
'''

name: 行应大写，并且不包含尾随句点。

使用完全限定的集合名称 (FQCN) 作为模块名称的一部分，如上例所示。对于 ansible-core 中的模块，请使用 ansible.builtin. 标识符，例如 ansible.builtin.debug。

如果您的示例使用布尔选项，请使用 yes/no 值。由于文档将布尔值生成为了 yes/no，因此示例也使用这些值可以使模块文档更加一致。

如果您的模块返回经常需要的 facts，那么如何使用它们的示例将很有帮助。

RETURN 块 

如果您的模块不返回任何内容（除了标准返回值），则模块的这一部分应写为：RETURN = r''' # ''' 否则，对于每个返回的值，请提供以下字段。除非另有说明，否则所有字段都是必需的。

返回值名称：

返回字段的名称。

description:: 此值代表什么的详细描述。大写并以句点结尾。
返回时机：: 返回此值的时间，例如 always、changed 或 success。这是一个字符串，可以包含任何人类可读的内容。
type:: 数据类型。
elements:: 如果 type='list'，则指定列表元素的数据类型。
示例：: 一个或多个示例。
version_added:: 仅当在 Ansible 初始发布后扩展此返回值时才需要，换句话说，这大于顶级 version_added 字段。这是一个字符串，而不是浮点数，例如，version_added: '2.3'。
包含：: 可选。要描述嵌套的返回值，请设置 type: dict 或 type: list/elements: dict，或者如果您确实需要，请使用 type: complex，并为每个子字段重复上述元素。

这里有两个 RETURN 部分示例，一个包含三个简单字段，另一个包含一个复杂的嵌套字段

RETURN = r'''
dest:
    description: Destination file/path.
    returned: success
    type: str
    sample: /path/to/file.txt
src:
    description: Source file used for the copy on the target machine.
    returned: changed
    type: str
    sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
md5sum:
    description: MD5 checksum of the file after running copy.
    returned: when supported
    type: str
    sample: 2a5aeecc61dc98c4d780b14b330e3282
'''

RETURN = r'''
packages:
    description: Information about package requirements.
    returned: success
    type: dict
    contains:
        missing:
            description: Packages that are missing from the system.
            returned: success
            type: list
            elements: str
            sample:
                - libmysqlclient-dev
                - libxml2-dev
        badversion:
            description: Packages that are installed but at bad versions.
            returned: success
            type: list
            elements: dict
            sample:
                - package: libxml2-dev
                  version: 2.9.4+dfsg1-2
                  constraint: ">= 3.0"
'''

Python 导入 

from module_utils.basic import AnsibleModule

不再允许使用“通配符”导入，例如 from module_utils.basic import *。

测试模块文档 

要在本地测试 Ansible 文档，请遵循说明。要测试集合中的文档，请参阅使用 antsibull-docs 构建文档站点。