一、Ansibledoc是什么
Ansibledoc 是 Ansible 的一个功能，旨在自动生成 Ansible 模块以及插件的文档。通过 Ansibledoc 可以自动生成标准的文件头部信息、模块的简介以及各项参数的描述与样例。Ansibledoc 采用 yum 的风格来进行文档描述，并且支持自定义标签。
二、Ansibledoc应用场景
Ansibledoc 可以应用于文档维护以及开发测试场景中：
1、 编写 Ansible 模块代码时，可以使用 Ansible doc 对参数的解释和参数的使用进行说明，提高代码的可阅读性，规范代码开发。
2、 对于 Ansible Role 模块，使用 Ansibledoc 可以自动生成 Markdown 格式的文档页面，方便用户查看使用方法和参数介绍。
三、Ansibledoc示例-生成Ansible Role模块文档
在 Ansible Role 模块中，我们通常将 Ansibledoc 插入到 role 文件夹下的 README.md 文件中，然后通过 GitHub Pages 或者使用其他 Markdown 渲染工具来查看文档。
示例：我们创建 ansibledoc_demo 角色，并设计一些参数：
- name: ansibledoc_demo
hosts: all
vars:
username: debugtalk
password: p@ssword
roles:
- role: ansible_role_test然后我们为这个角色创建 README.md 文件，并插入 Ansibledoc 代码：
# Ansible Role: ansible_role_test
Insert your introduction here.
## Role variables
### Required variables
| Variable Name | Variable Description | Default Value |
|---------------|----------------------|---------------|
|`username` | | |
|`password` | | |
## Example Playbook
- name: ansibledoc_demo
hosts: all
vars:
username: debugtalk
password: p@ssword
roles:
- role: ansible_role_test
## License
Licensed under the [MIT License](https://opensource.org/licenses/MIT).接下来我们可以使用命令 ansible-doc ansible_role_test 来生成文档，并且查看生成的日志信息：
$ ansible-doc ansible_role_test这个命令会将文档生成到 /etc/ansible/roles/ansible_role_test/README.md 文件中。打开 README.md 文件，我们可以查看生成的文档信息：
# Module: ansible_role_test
Insert your description here.
## Role variables
### Required variables
| Variable Name | Default | Description |
|---------------|---------|-------------|
| username | | |
| password | | |
## Example
Insert your example here.
## License
Licensed under the [MIT License](https://opensource.org/licenses/MIT).四、自定义Ansibledoc标签
Ansibledoc 支持无限制的自定义标签。如果您将自定义标签应用于多个模块或插件中，您可以通过使用 ansible-doc --metadata 来预定义标签。
示例：我们创建一个自定义标签，用于描述 Ansible Role 模块的兼容性：
# Ansible Role: ansible_role_test
Insert your introduction here.
## Role variables
### Required variables
| Variable Name | Variable Description | Default Value |
|---------------|----------------------|---------------|
|`username` | | |
|`password` | | |
## Compatibility
| When used with | Versions |
|----------------|----------|
| Ubuntu | 18.04 |
| CentOS | 7 |
## Example Playbook
- name: ansibledoc_demo
hosts: all
vars:
username: debugtalk
password: p@ssword
roles:
- role: ansible_role_test
## License
Licensed under the [MIT License](https://opensource.org/licenses/MIT).接下来，我们可以使用 --metadata 标记来添加自定义标签，在运行 ansible-role-doc 命令时将会自动应用。
$ ansible-doc ansible_role_test --metadata 'tags=dict ansible_version=2.2' 以上命令将会应用新的自定义标签，并且关闭标准 Ansibledoc 标签。
结论
Ansibledoc 作为 Ansible 的一个功能，可以帮助我们更好地维护文档及规范代码。通过对 Ansibledoc 的详细了解，在使用 Ansibledoc 进行文档开发时，我们可以很方便的开始，先自行阅读定义好的标签并且应用到文档中。在实际使用中，您还可以使用 Ansibledoc 来生成其他类型的模块或插件的文档，例如 Ansible Playbook 以及 Ansible Plugin。祝大家愉快的编写 Ansible 脚本！
