时间戳

首页 > 解决方案 > 如何从 ansible-modules 生成文档

ansible - 如何从 ansible-modules 生成文档

问题描述

我们正在使用像 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 环境变量，但它只会输出一个几乎为空的文件antsibull-docs collection --use-current --dest-dir ~/docs collectionname

我也不知道这是否是正确的方法。

那么我能做什么呢？

标签： ansibledocumentation

解决方案

您可以使用 antsibull-docs 为自制集合生成文档（rst）。
以下是生成文档的过程。

  1. 安装

安装ansible。

pip install ansible-base
ansible --version
ansible 2.10.5
  1. 反牛安装

克隆antsibull repo并安装。

pip install --upgrade pip
git clone https://github.com/ansible-community/antsibull.git
cd antsibull/
pip install poetry
poetry install
cd ..
  1. 创建收藏目录

这一次，在当前（工作）目录中创建一个集合目录。
根据自制集合更改命名空间。

mkdir -p collections/ansible_collections/{namespace}/
  1. 将您的集合移动到命名空间目录
mv {your_collection} collections/ansible_collections/{namespace}/
  1. ansible.cfg 创建

创建 ansible.cfg 以指定集合目录路径。

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
  1. 为模块生成 .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

这样，模块 .rst 文档就在 build/plugin_docs 目录中生成。
如果发生构建错误，请检查 your_collection 目录下的galaxy.yml 中的参数是否错误。

推荐阅读