Terraform-docs GitHub Actions 项目启动与配置教程

1. 项目的目录结构及介绍

terraform-docs/gh-actions 项目是一个开源项目，旨在使用 GitHub Actions 自动化生成 Terraform 配置文档。以下是项目的目录结构及其简要介绍：

• /.github/workflows: 存放 GitHub Actions 工作流文件，定义了自动化任务的执行流程。
• /docs: 包含项目文档，可能包含一些示例和说明。
• /src: 源代码目录，包含了实现自动化的脚本和程序。

2. 项目的启动文件介绍

在 .github/workflows 目录下，通常会有一个或多个 YAML 格式的文件，这些文件是 GitHub Actions 的配置文件，也是项目的启动文件。以下是一个基本的启动文件示例：

name: Generate Terraform Documentation

on:
  push:
    branches:
      - main

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.x'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install terraform-docs
    - name: Generate documentation
      run: terraform-docs markdown ./path/to/terraform/config
    - name: Upload documentation
      uses: actions/create-release@v1
      with:
        tag_name: ${{ github.ref }}
        release_name: Release ${{ github.ref }}
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    - name: Publish documentation
      uses: actions/github-release-asset@v1
      with:
        upload_url: ${{ steps.create_release.outputs.upload_url }}
        asset_path: ./path/to/generated/docs
        asset_name: terraform-documentation.md
        asset_content_type: application/markdown

这个配置文件定义了一个 GitHub Actions 工作流，当向 main 分支推送代码时自动触发。它包括以下步骤：

• 检出代码。
• 设置 Python 环境。
• 安装依赖。
• 生成 Terraform 文档。
• 创建一个 GitHub Release。
• 发布文档到 Release。

3. 项目的配置文件介绍

在这个项目中，主要的配置文件是 GitHub Actions 的工作流文件，如上所述。除此之外，还可能包含一些用于自定义 Terraform-docs 生成过程的配置文件，例如：

• /.terraform-docs.yml：这是一个 Terraform-docs 的配置文件，可以定义文档生成的各种选项，如排序规则、模板等。

下面是一个简单的配置文件示例：

# .terraform-docs.yml
sort:
  params: false
  outputs: false
  providers: false
  resources: true
  locals: false
  variables: true

template:
  header: '# Terraform 配置文档\n\n'
  resource:
    name: '## {{ .Resource }}\n\n'
    type: '### 类型：{{ .Type }}\n\n'
    description: '#### 描述：{{ if .Description }}{{ .Description }}{{ else }}无描述{{ end }}\n\n'
    attributes:
      name: '#### 属性：\n'
      value: '* {{ .Name }}: {{ .Value }}\n'

这个配置文件定义了文档的排序规则和模板，以自定义 Terraform 配置文档的生成格式。