以前、Ansible Collectionsのモジュールドキュメント自動生成方法について以下の記事を書きました。
これは、docsディレクトリ配下にモジュールのrstの自動生成とREADMEの自動更新をするツールを使ったものになっています。
今回は、別のツールを使ってSphinx経由で公式と同じドキュメント形式(VMwareの例)の生成方法について紹介します。
環境説明
今回の環境では、次のバージョンを使用しています。
| 項目 | バージョン |
|---|---|
| Python | 3.6.8 |
| Ansible Base | 2.10.5 |
ドキュメント生成ツール
antsibull を使う事でrstを自動生成してSphinx経由でHTMLのドキュメントを生成することが出来ます。
ドキュメント生成方法
事前準備
Ansibleをインストールします。
|
1 2 |
(venv)$ pip install ansible-base |
antsibullインストール
antsibullをインストールします。
|
1 2 3 4 5 6 7 |
(venv)$ pip install --upgrade pip (venv)$ git clone https://github.com/ansible-community/antsibull.git (venv)$ cd antsibull/ (venv)$ pip install poetry (venv)$ poetry install (venv)$ cd .. |
自動的にSphinxもインストールしてくれます。
次にSphinxのテーマをインストールします。
|
1 2 |
(venv)$ pip install sphinx-rtd-theme |
Collectionsを作成
今回は以下のサンプルを使用します。
以下の手順でサンプルのcollectionを作成します。
|
1 2 3 |
(venv)$ mkdir -p collections/ansible_collections/sample (venv)$ git clone https://github.com/sky-joker/sample_generate_collection_doc.git collections/ansible_collections/sample/sample_generate_collection_doc |
Ansible設定
今回は作業用ディレクトリにCollectionを作成したので、ansible.cfgでパスの設定をします。
|
1 2 |
(venv)$ vi ansible.cfg |
|
1 2 3 |
[defaults] COLLECTIONS_PATHS = 作業ディレクトリのフルパス + /collections を設定してください(例: /home/user/xxxx/workdir/collections) |
設定が反映されたことを確認します。
|
1 2 3 |
(venv)$ ansible-config dump --only-changed COLLECTIONS_PATHS(/{設定したパス}/ansible.cfg) = ['/{設定したパス}/collections'] |
サンプルcollectionのモジュールドキュメントが ansible-doc で表示されるか確認します。
|
1 2 |
(venv)$ ansible-doc sample.sample_generate_collection_doc.sample_collections_doc |
SphinxでHTML生成
Sphinxの作業用ディレクトリを作成して初期化します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
(venv)$ mkdir doc_build (venv)$ cd doc_build/ (venv)$ sphinx-quickstart (snip) You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: The project name will occur in several places in the built documentation. > Project name: Sample > Author name(s): sky-joker > Project release []: 0.1 If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > Project language [en]: (snip) |
Sphinxの設定を追加します。
|
1 2 |
(venv)$ vi conf.py |
Sphinxのテーマ(sphinx_rtd_theme)とextensionsの設定を追加します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
(snip) # sys.path.insert(0, os.path.abspath('.')) import sphinx_rtd_theme # -- Project information ----------------------------------------------------- (snip) #extensions = [ #] extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx_antsibull_ext', 'sphinx_rtd_theme'] (snip) #html_theme = 'alabaster' html_theme = "sphinx_rtd_theme" (snip) |
設定が終わったらディレクトリを移動します。
|
1 2 3 4 |
(venv)$ cd .. (venv)$ ls ansible.cfg antsibull collections doc_build venv |
次のコマンドを実行してCollectionのrstを生成します。
以下の例では index.rst が上書きされて sample_collections_doc_module.rst のモジュールドキュメントが生成されています。
|
1 2 3 4 |
(venv)$ antsibull-docs collection --use-current --squash-hierarchy --dest-dir doc_build sample.sample_generate_collection_doc (venv)$ ls doc_build/ _build conf.py index.rst make.bat Makefile sample_collections_doc_module.rst _static _templates |
次にrstからHTMLを生成します。
|
1 2 3 4 5 |
(venv)$ cd doc_build (venv)$ make html (venv)$ ls _build/html/ genindex.html index.html objects.inv sample_collections_doc_module.html search.html searchindex.js _sources _static |
_build/html にHTMLが生成されているので index.html をブラウザで表示してみてください。
公式のドキュメントのようなCollectionのドキュメントが確認できると思います。
最後に
このように、rstだけではなく、HTML化したいという要件が合った場合は antsibull を使うことで可能です。
また collection_prep の場合はPython 3.8以上が必要でしたが、今回はPython3.6でも問題なく動きます。
antsibull はJinja2テンプレートを使ってrstを生成しているので、テンプレートを修正すれば要件に合わせたドキュメントの自動生成も可能だと思います。
2つの使い分けとしては、こんな感じだと思います。
- collection_prep
- リポジトリ内でCollectionのドキュメントを参照させる場合
- antsibull
- リポジトリ内だけではなく、HTMLドキュメントも生成したい場合
今後、Collectionを開発していく方の参考になれば幸いです！
