Ansible 标记语言

Ansible 标记语言允许您为 Ansible 模块、插件和角色格式化并构建文档。它支持向文本添加基础格式（如粗体、斜体、代码和水平线），以及创建各种引用，如 URL、超链接、Ansible 模块引用和 RST 引用。Ansible 标记语言在 2023 年随 ansible-core 2.15 版本进行了扩展。现在，它允许您针对值、模块/插件选项、返回值、环境变量以及插件引用应用语义标记。

本页面记录了当前支持的 Ansible 标记语言。

模块文档中的语义标记

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

语义标记的正确格式如下：

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() 和 RV() 的使用规则非常严格。您必须遵守语法规则，以便文档渲染器能够分别为选项和返回值创建超链接。

允许的语法如下：

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

选项名称可以通过列出以点分隔的选项路径来引用子选项。例如，如果您有一个选项 foo 以及子选项 bar，则必须使用 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 事实。

模块文档内部链接

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

R() 用于带有标题的交叉引用（Ansible 2.10 起支持）。例如：See R(Cisco IOS Platform Guide,ios_platform_options)。请使用 RST 锚点进行交叉引用。详情请参见添加锚点。
- 对于集合外部的链接，如果可用，请使用 R()。否则，请使用带有完整 URL（而非相对链接）的 U() 或 L()。
- 要引用集合中的一组模块，请使用 R()。当集合不是合适的粒度时，请使用 C(..)，例如：
  - Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.
  - The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.
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.
M() 用于模块名称。例如：See M(ansible.builtin.yum) or M(community.general.apt_rpm)。
- 必须使用 FQCN（完全限定集合名称），短名称会导致链接失效；对于 ansible-core 中的模块，请使用 ansible.builtin。
P() 用于插件名称（ansible-core 2.15 起支持）。例如：See P(ansible.builtin.file#lookup) or P(community.general.json_query#filter)。
- 这也支持引用角色：P(community.sops.install#role)。
- 必须使用 FQCN，短名称会导致链接失效；对于 ansible-core 中的插件，请使用 ansible.builtin。
O() 和 RV() 也可以进行链接，请参阅关于它们语法的章节。

注意

如果您要创建自己的文档网站，则需要使用 intersphinx 扩展，将 R()、M()、P()、O() 和 RV() 转换为正确的链接。

模块文档中的格式化宏

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

可能的宏包括：

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

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