Terraform-docs递归生成子模块文档指南

Terraform-docs递归生成子模块文档指南

terraform-docs Generate documentation from Terraform modules in various output formats 项目地址: https://gitcode.com/gh_mirrors/te/terraform-docs

什么是递归子模块文档生成

在Terraform项目中，我们经常会使用模块化的设计方式，将基础设施代码分解为多个可重用的子模块。Terraform-docs工具从0.15.0版本开始，提供了递归生成子模块文档的功能，可以一次性为主模块及其所有子模块生成文档。

为什么需要递归生成文档

传统方式下，我们需要为每个子模块单独运行文档生成命令，这种方式存在几个问题：

1. 操作繁琐，需要多次执行命令
2. 容易遗漏某些子模块
3. 难以保持文档风格的一致性

递归生成功能解决了这些问题，通过一条命令即可完成整个项目所有模块的文档生成工作。

基本使用方法

命令行方式

假设我们有以下项目结构：

.
├── README.md
├── main.tf
├── modules
│   └── my-sub-module
│       ├── README.md
│       ├── main.tf
│       ├── variables.tf
│       └── versions.tf
├── outputs.tf
├── variables.tf
└── versions.tf

要递归生成文档，只需执行：

terraform-docs markdown --recursive --output-file README.md .

重要注意事项

1. 递归生成功能必须配合--output-file参数使用
2. 默认情况下会包含主模块文档
3. 子模块查找路径默认为modules目录

高级配置选项

自定义子模块路径

如果子模块不在默认的modules目录下，可以使用--recursive-path指定：

terraform-docs markdown --recursive --recursive-path custom-modules --output-file README.md .

排除主模块

如果只需要生成子模块文档，可以排除主模块：

terraform-docs markdown --recursive --recursive-include-main=false --output-file README.md .

配置文件方式

除了命令行参数，还可以通过.terraform-docs.yml配置文件启用递归生成：

formatter: markdown table

recursive:
  enabled: true

output:
  file: README.md
  mode: inject

然后只需运行：

terraform-docs .

子模块个性化配置

每个子模块可以拥有自己的.terraform-docs.yml配置文件，用于覆盖根模块的配置。这使得我们可以：

1. 为特定子模块设置不同的文档格式
2. 调整子模块的文档生成规则
3. 自定义子模块的文档内容

最佳实践建议

1. 保持一致性：建议在根模块配置统一的文档格式，除非有特殊需求
2. 合理组织子模块：将相关子模块放在同一目录下便于管理
3. 版本控制：将生成的文档纳入版本控制，方便追踪变更
4. CI/CD集成：在自动化流程中加入文档生成步骤

通过合理使用terraform-docs的递归生成功能，可以大幅提升Terraform项目的文档维护效率，确保项目文档的完整性和一致性。

terraform-docs Generate documentation from Terraform modules in various output formats 项目地址: https://gitcode.com/gh_mirrors/te/terraform-docs