如何从 ansible-modules 生成文档

Question

我们正在像 openstack 那样使用 ansible 模块开发一个 ansible 集合：https://github.com/openstack/ansible-collections-openstack

如何从 ansible wiki 中的模块生成文档？ https://docs.ansible.com/ansible/2.8/modules/os_auth_module.html#os-auth-module

我在互联网上找到了这个，但我无法让 antsibull 工作 https://www.die-welt.net/2020/07/building-documentation-for-ansible-collections-using-antsibull/ 问题在于，尽管设置了 ANSIBLE_COLLECTIONS_PATH env var，它只会输出一个几乎为空的文件 antsibull-docs collection --use-current --dest-dir ~/docs collectionname

我也不知道这样做是否正确。

那我该怎么办？

Answer 1

您可以使用 antsibull-docs.
为 self-made collection 生成文档（第一个）以下是生成文件的过程。

ansible 安装

安装ansible。

pip install ansible-base
ansible --version
ansible 2.10.5

antsibull 安装

克隆 antsibull 存储库并安装。

pip install --upgrade pip
git clone https://github.com/ansible-community/antsibull.git
cd antsibull/
pip install poetry
poetry install
cd ..

这次，在当前（工作）目录中创建一个 collections 目录。
根据 self-made collections.

更改命名空间

mkdir -p collections/ansible_collections/{namespace}/

将您的collection移动到命名空间目录

mv {your_collection} collections/ansible_collections/{namespace}/

ansible.cfg创作

创建一个ansible.cfg来指定collection目录路径。

vi ansible.cfg

[defaults]
COLLECTIONS_PATHS = {your_working_directory_path}/collections

检查配置是否反映出来。

ansible-config dump --only-changed
COLLECTIONS_PATHS({your_working_directory_path}/ansible.cfg) = ['{your_working_directory_path}/collections']

查看模块文件可以用ansible-doc查看。

ansible-doc namespace.your_collection.module_name

为模块生成 .rst 文件

mkdir -p build/plugin_docs
antsibull-docs collection --use-current --squash-hierarchy --dest-dir ./build/plugin_docs namespace.your_collection
ls ./build/plugin_docs

这样，在build/plugin_docs 目录中生成了模块.rst 文件。
如果出现构建错误，请检查your_collection目录中的galaxy.yml中的参数是否有误。

如何从 ansible-modules 生成文档

How to generate a documentation from ansible-modules

documentation

ansible