これは Ansible Advent Calendar 2020 の12日目の記事になります。
Contents
Ansibleのモジュールドキュメントについて
Ansible 2.10からモジュールやプラグインなどはCollections化されて提供されるようになった事や、Galaxy NGを使う事でローカルにAutomation Hubを構築して組織内で開発したCollectionを共有することが出来ることから、これから自作モジュールを目的に合わせて作成していく場合はCollection化される案件が増えてくるのではないかと想像しています。（CollectionsはAnsible 2.9でも使用可能）
その時に出てくる課題の一つがドキュメント作成かと思います。
モジュールの仕様をドキュメント化して提供したいが、一つ一つ作成するのは手間です。正直めんどくさいです。やりたくないです。やりたくないです。（大事なことなので2回言いました）
AnsibleのドキュメントはSphinxでビルドされ提供されています。
Ansible 2.9まではモジュールがまとまって管理されていたため、次の手順でビルドできていました。
ところが、Collectionsからモジュールは個別リポジトリで管理されるようになったため上記手順のようにSphinxでビルドしてドキュメント生成が出来なくなっていますが、別の手段でモジュールドキュメントの元になるrstを自動で生成することが出来ます。
今回はCollectionsのモジュールドキュメントのrstを自動で生成するやり方について紹介したいと思います。
collection_prep
Collectionsのドキュメント(rst)は次のツールで自動生成することが可能です。
要件として Python>=3.8 が必要になります。
このツールでは、以下の事が可能です
- モジュールのドキュメントブロック(DOCUMENTATION/EXAMPLES/RETURN)からrstを自動生成
- 自動生成したドキュメントのリンクをREADMEに反映
- meta/runtime.ymlの情報をREADMEに反映
それでは、どう使うかを説明していきます。
Collectionsのドキュメントを自動生成する
今回は、以下にサンプルを用意していますので、これを元に説明します。
サンプルモジュールについて
サンプルでは、何もしないモジュールを用意しています。
今回、大事なのは以下のドキュメントブロックの中身です。
以下がドキュメントの元になる定義です。
これをパースしてrstを生成します。
|
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 |
(snip) DOCUMENTATION = r''' module: sample_collection_doc short_description: sample collection doc module author: - sky-joker (@sky-joker) description: - This module does nothing requirements: - python >= 2.7 options: param1: description: - This parameter can be anything. type: str default: hoge param2: description: - This parameter can be anything. type: str default: fuga param3: description: - This parameter can be anything. type: str default: hogefuga ''' EXAMPLES = r''' - name: test sample_collection_doc: param1: hoge ''' RETURN = r''' param1: description: param1 value returned: always type: str sample: hoge param2: description: param2 value returned: always type: str sample: fuga param3: description: param3 value returned: always type: str sample: hogefuga ''' (snip) |
README設定
READMEに次のアンカーを仕込みます。
|
1 2 3 4 5 6 7 8 |
## sample_generate_collection_doc <!--start requires_ansible--> <!--end requires_ansible--> <!--start collection content--> <!--end collection content--> |
requires_ansible の間はruntime.ymlで定義したCollectionがサポートするAnsibleの情報が入ります。
collection content の間は自動で生成したモジュールドキュメントのリンク情報が入ります。
ちなみに、ドキュメントのリンクで使うURLは galaxy.yml に定義した repository の値が使われます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
namespace: sample name: sample_generate_collection_doc readme: README.md authors: - sky-joker (@sky-joker) description: license: license_file: LICENSE tags: - sample repository: https://github.com/sky-joker/sample_generate_collection_doc.git homepage: https://github.com/sky-joker/sample_generate_collection_doc issues: https://github.com/sky-joker/sample_generate_collection_doc/issues |
ドキュメント自動生成
それでは、Collectionのモジュールドキュメント自動生成してみましょう。
ツールを動作させるにはPython3.8が必要なので、ここではDockerでコンテナを使います。
|
1 2 3 |
[root@localhost ~]# docker run -itd --name py38 --rm python:3.8 [root@localhost ~]# docker exec -it py38 bash |
それでは collection_prep をインストールしてみます。
|
1 2 3 4 5 6 7 8 9 |
root@e66be603b133:/# cd root@e66be603b133:~# pwd /root root@e66be603b133:~# git clone https://github.com/ansible-network/collection_prep.git root@e66be603b133:~# cd collection_prep/ root@e66be603b133:~/collection_prep# pip install . root@e66be603b133:~/collection_prep# which collection_prep_add_docs /usr/local/bin/collection_prep_add_docs |
それでは、サンプルのモジュールドキュメントを自動で生成してみましょう。
サンプルをクローンしてコマンドを実行します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
root@e66be603b133:~/collection_prep# cd .. root@e66be603b133:~# git clone https://github.com/sky-joker/sample_generate_collection_doc.git root@e66be603b133:~# ls collection_prep sample_generate_collection_doc root@e66be603b133:~# collection_prep_add_docs -p sample_generate_collection_doc/ INFO Setting collection name to sample.sample_generate_collection_doc INFO Setting GitHub repository url to https://github.com/sky-joker/sample_generate_collection_doc.git INFO Making docs directory /root/sample_generate_collection_doc/docs INFO Process content in /root/sample_generate_collection_doc/plugins/modules INFO Processing /root/sample_generate_collection_doc/plugins/modules/sample_collections_doc.py INFO Processing 'modules' for README INFO README.md updated INFO README.md updated with ansible compatibility information |
ドキュメントが生成された確認してみましょう。
生成されたドキュメントは docs ディレクトリにあります。
|
1 2 3 |
root@e66be603b133:~# ls sample_generate_collection_doc/docs/ sample.sample_generate_collection_doc.sample_collection_doc_module.rst |
中身がrstで生成されていることが確認できます。
|
1 2 3 4 5 6 7 8 9 10 11 |
root@e66be603b133:~# cat sample_generate_collection_doc/docs/sample.sample_generate_collection_doc.sample_collection_doc_module.rst .. _sample.sample_generate_collection_doc.sample_collection_doc_module: *********************************************************** sample.sample_generate_collection_doc.sample_collection_doc *********************************************************** **sample collection doc module** (snip) |
READMEも見てみましょう。
こんな感じでアップデートされます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
root@e66be603b133:~# cat sample_generate_collection_doc/README.md # sample_generate_collection_doc <!--start requires_ansible--> ## Ansible version compatibility This collection has been tested against following Ansible versions: **>=2.9.10**. Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible. <!--end requires_ansible--> <!--start collection content--> ### Modules Name | Description --- | --- [sample.sample_generate_collection_doc.sample_collection_doc](https://github.com/sky-joker/sample_generate_collection_doc/blob/main/docs/sample.sample_generate_collection_doc.sample_collection_doc_module.rst)|sample collection doc module <!--end collection content--> |
Collectionのモジュールドキュメント(rst)生成とREADMEへの反映の自動化が出来ました 🙂
最後に
これでrstは作れたので、後はレンダリングできるツール 1 を使って確認、GitHub/GitLabにそのままアップして確認、Sphinxでビルドして確認ができると思います。
ビルドも自動化してしまえば、ドキュメント作成も効率化出来てめんどくさくなくなりますね 🙂
今後、Collectionを開発していく方の参考になれば幸いです！
