Ansibledoc詳解

一、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 腳本！
原創文章，作者：小藍，如若轉載，請註明出處：https://www.506064.com/zh-hant/n/280800.html