この投稿はAnsible 3 Advent Calendar 2019の24日目の記事です。
Ansibleのモジュールに書かれているドキュメントですが ansible-doc を使って確認することができます。
しかし、実際にWebページで表示された時にどう見えるか？までは確認できません。
そこで、モジュールのHTMLドキュメントをビルドして確認する方法を書いてみようと思います。
公式ドキュメント
環境
| 項目 | バージョン |
|---|---|
| Python | 3.6 |
Ansibleリポジトリクローン
Ansibleリポジトリをクローンします。
|
1 2 |
[root@localhost doc]# git clone https://github.com/ansible/ansible.git |
venv作成・有効化
venvを作成します。
|
1 2 3 |
[root@localhost doc]# cd ansible/ [root@localhost ansible]# python3 -m venv venv |
activateを実行します。
|
1 2 3 4 |
[root@localhost ansible]# python3 -m venv venv [root@localhost ansible]# . venv/bin/activate (venv) [root@localhost ansible]# |
モジュールのインストール
必要なモジュールをインストールします。
|
1 2 |
(venv) [root@localhost ansible]# pip install -r requirements.txt -r docs/docsite/requirements.txt |
これで準備が整いました。
自作モジュールのドキュメントを作成
ここでは以下の自作モジュール(output_name)のドキュメントを作成してみます。
|
1 2 3 4 5 |
(venv) [root@localhost ansible]# mkdir lib/ansible/modules/salf-made (venv) [root@localhost ansible]# touch lib/ansible/modules/__init__.py (venv) [root@localhost ansible]# vi lib/ansible/modules/output_name.py 以下のソースを貼り付ける |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 |
#!/usr/bin/python # -*- coding: utf-8 -*- # Copyright: (c) 2018, sky_joker # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type ANSIBLE_METADATA = { 'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community' } DOCUMENTATION = ''' module: output_name short_description: module that outputs a name. author: - sky_joker (@sky-joker) version_added: 2.x description: - Output the specified name. requirements: - python >= 2.7 options: name: description: - Specify name. required: True ''' EXAMPLES = ''' --- - output_name: name: taro register: r - debug: msg="{{ r }}" ''' from ansible.module_utils.basic import AnsibleModule def main(): argument_spec = dict( name=dict(type="str", required=True) ) module = AnsibleModule(argument_spec, supports_check_mode=True) result = dict(changed=False) name = module.params['name'] if(name): result['name'] = name module.exit_json(**result) else: module.fail_json(msg="Please specify name.") if __name__ == "__main__": main() |
HTMLドキュメントを作成します。
MODULES にドキュメント化したいモジュールを指定します。
複数指定する場合は ,(カンマ) 区切りで指定します。
|
1 2 |
(venv) [root@localhost ansible]# MODULES=output_name make webdocs |
ドキュメント確認
ドキュメント作成が完了したら、以下のパスへ移動します。
|
1 2 |
(venv) [root@localhost ansible]# cd docs/docsite/_build/html/ |
静的ドキュメントを確認するだけなので、ここではPython3のHTTPサーバのモジュールを使用してHTTPサーバを起動します。
|
1 2 |
(venv) [root@localhost html]# python3 -m http.server |
http://ip:8000 へアクセスすれば以下のようにドキュメントを確認することができます。
これで、Sphinxでビルドされたモジュールのドキュメントがブラウザから確認できました 🙂
もし、ドキュメント関連でPRしたい場合、一度このやり方で確認してからPRするといいですね 🙂
