介绍

ansible-doc 是 Ansible 自带 插件/模块文档查看工具，作用类似 Linux 的 man，用来 查看本地已安装模块、插件的文档、参数、示例，不需要联网。

命令格式

ansible-doc [选项] [插件/模块名]

参数

参数	全称	作用
`-h`	`--help`	查看 ansible-doc 自身帮助
`-l`	`--list`	列出所有插件（默认类型 module），可过滤
`-s`	`--snippet`	输出 playbook YAML 片段模板，直接复制使用
`-t`	`--type`	指定插件类型，默认 `module`
`-M`	`--module-path`	指定自定义模块目录路径
`-F`	`--list_files`	列出插件名称 + 源码文件路径
`-j`	`--json`	JSON 格式输出文档，适合脚本解析
`-v`	`--verbose`	增加详细信息，`-vvv` 调试
`--version`		查看 ansible 版本

`-t` 支持的插件类型

module（模块，默认）、lookup、inventory、callback、connection、become、cache、filter、test、strategy、role、keyword、cliconf、httpapi、netconf、shell、vars

例子

1. 列出所有模块

ansible-doc -l

过滤查找 yum 相关模块

ansible-doc -l | grep yum

过滤查找 apt 相关模块

ansible-doc -l | grep apt

2. 查看模块完整文档（重点）

ansible-doc file

文档结构包含：

模块简介
参数列表（= 代表必填参数，- 可选）
选项说明、默认值
模块返回值
Playbook 示例

3. 快速获取 playbook 模板片段（高频）

ansible-doc -s file

输出示例：

- name: Manage files and file properties
  file:
    path:           # Path to the file being managed.
    state:          # If `absent`, directories will be recursively deleted.
    mode:           # Permissions of the file or directory.

4. 查看 lookup 查找插件（指定插件类型）

ansible-doc -t lookup file

5. 查看模块源码路径

ansible-doc -F ping

6. JSON 输出文档（自动化解析）

ansible-doc -j ping

常见坑

ansible 2.10 之后模块都放到 collections（集合），很多模块全名带命名空间 community.general.*，直接写短名字可能找不到。
ansible-doc 读取本地安装的集合文档，如果集合没有安装，就看不到模块文档。
```
# 安装集合示例
ansible-galaxy collection install community.general
```
-l 列出的插件数量很大，一般配合 grep 检索。
自定义模块：使用 -M 指定模块目录，才能被 ansible-doc 识别。
```
ansible-doc -M ./library my_custom_module
```

和在线文档区别

ansible-doc：本地文档，版本和你当前 ansible 版本严格一致，离线可用。
官网 docs：在线文档，对应最新版本，本地 ansible 版本低时会有差异。

原文出处：/show_1GW45uTcKihE.html

介绍