thegeeklab/ansible-doctor

ansible-doctor

基于注解的Ansible角色文档生成工具

概述和主要用途

ansible-doctor是一款基于注解的文档生成器，专为Ansible角色设计，使用Jinja2模板生成文档。该工具源于ansible-autodoc项目的理念（部分代码基于此），支持默认模板（如readme）和自定义模板，可输出多种格式（如README、HTML、XML等）。ansible-doctor适用于CI流水线集成，补充现有测试和部署流程，确保文档自动更新。发布渠道包括Python包（GitHub、PyPI）和Docker镜像（Docker Hub、Quay.io）。

核心功能和特性

• 注解驱动文档生成：通过简单注解自动提取Ansible角色信息，生成结构化文档
• Jinja2模板系统：内置默认readme模板，支持自定义模板定制输出格式
• 多格式输出：可生成README、HTML、XML等多种格式文档
• CI流水线集成：设计用于CI环境，自动化文档更新流程
• 多平台支持：提供Python包和Docker镜像，适配不同部署需求

使用场景和适用范围

• Ansible角色开发：自动生成和维护角色文档，减少手动编写工作量
• CI/CD流水线：集成到现有测试部署流程，确保文档与代码同步更新
• 自定义文档需求：通过自定义Jinja2模板生成特定格式的文档（如项目官网HTML文档）

使用方法和配置说明

Docker镜像获取

可从Docker Hub或Quay.io获取最新镜像：

bash
# 从Docker Hub拉取
docker pull docker.xuanyuan.run/thegeeklab/ansible-doctor:latest

# 从Quay.io拉取
docker pull ***-quay.xuanyuan.run/thegeeklab/ansible-doctor:latest

基本使用示例

在本地Ansible角色目录运行，使用默认模板生成README文档：

bash
docker run --rm -v $(pwd):/data docker.xuanyuan.run/thegeeklab/ansible-doctor ansible-doctor -p /data

自定义模板使用

指定自定义模板目录生成文档：

bash
docker run --rm -v $(pwd):/data -v /path/to/custom/templates:/templates docker.xuanyuan.run/thegeeklab/ansible-doctor ansible-doctor -p /data -t /templates/custom-template

完整文档

更多配置参数、模板语法和高级用法，请参考官方文档：https://ansible-doctor.geekdocs.de/

贡献者

感谢所有https://github.com/thegeeklab/ansible-doctor/graphs/contributors%E3%80%82%E5%A6%82%E9%9C%80%E8%B4%A1%E7%8C%AE%EF%BC%8C%E8%AF%B7%E5%8F%82%E9%98%85https://github.com/thegeeklab/ansible-doctor/blob/main/CONTRIBUTING.md%E3%80%82

许可证

本项目采用GPL-3.0许可证 - 详见https://github.com/thegeeklab/ansible-doctor/blob/main/LICENSE%E6%96%87%E4%BB%B6%E3%80%82