Ansible教程：ansible-doc 查看文档命令-马育民老师

# 介绍

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

# 命令格式

```bash
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. 列出所有模块
```bash
ansible-doc -l
```

##### 过滤查找 yum 相关模块

```
ansible-doc -l | grep yum
```

##### 过滤查找 apt 相关模块

```
ansible-doc -l | grep apt
```

### 2. 查看模块完整文档（重点）
```bash
ansible-doc file
```
文档结构包含：
- 模块简介
- 参数列表（`=` 代表必填参数，`-` 可选）
- 选项说明、默认值
- 模块返回值
- Playbook 示例

### 3. 快速获取 playbook 模板片段（高频）
```bash
ansible-doc -s file
```
输出示例：
```yaml
- 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 查找插件（指定插件类型）
```bash
ansible-doc -t lookup file
```

### 5. 查看模块源码路径
```bash
ansible-doc -F ping
```

### 6. JSON 输出文档（自动化解析）
```bash
ansible-doc -j ping
```

# 常见坑

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

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

原文出处：/show_1GW45uTcKihE.html