modules-terraform-docs.yaml

---
# GitHub Actions workflow to automatically generate documentation from the .tf files of the module.
# The generated documentation will be injected between AsciiDoc comments on the README.adoc.
#
# IMPORTANT: This workflow is called by other workflows in our DevOps Stack repositories and it is centralized here in 
# order to be easily maintained across modules. Because of this, please make sure you're not introducing any breaking 
# changes when modifying this workflow.

name: "modules-terraform-docs"

on:
  workflow_call:
    inputs:
      variants:
        description: "List of the variants folders as a comma-separated list inside a string (i.e. 'eks,aks,sks')."
        type: string
        required: false
        default: ""

env:
  ARGS: "--hide-empty=true --sort=false" # Do not show empty sections and do not sort items
  DOCS_TPL: "// BEGIN_TF_DOCS\n{{ .Content }}\n// END_TF_DOCS" # Define template compatible with AsciiDoc
  TABLES_TPL: "// BEGIN_TF_TABLES\n{{ .Content }}\n// END_TF_TABLES" # Define template compatible with AsciiDoc

jobs:
  terraform-docs:
    runs-on: ubuntu-latest

    steps:
    - name: "Check out the repository"
      uses: actions/checkout@v4
      with:
        ref: ${{ github.event.pull_request.head.ref }}

    - name: "Generate Terraform docs"
      uses: terraform-docs/gh-actions@v1.3.0
      with:
        working-dir: .
        indention: 3
        output-format: asciidoc document
        output-file: README.adoc
        output-method: inject
        template: ${{ env.DOCS_TPL }}
        args: ${{ env.ARGS }}
        git-push: false

    - name: "Generate Terraform tables"
      uses: terraform-docs/gh-actions@v1.3.0
      with:
        working-dir: .
        indention: 1 # Since the headings are not read inside the collapsible block we can indent as 1
        output-format: asciidoc table
        output-file: README.adoc
        output-method: inject
        template: ${{ env.TABLES_TPL }}
        args: ${{ env.ARGS }}
        git-push: false

    - name: "Generate Terraform docs for the variants"
      if: ${{ inputs.variants != '' }}
      uses: terraform-docs/gh-actions@v1.3.0
      with:
        working-dir: ${{ inputs.variants }}
        indention: 3
        output-format: asciidoc document
        output-file: README.adoc
        output-method: inject
        template: ${{ env.DOCS_TPL }}
        args: ${{ env.ARGS }}
        git-push: false

    - name: "Generate Terraform tables for the variants"
      if: ${{ inputs.variants != '' }}
      uses: terraform-docs/gh-actions@v1.3.0
      with:
        working-dir: ${{ inputs.variants }}
        indention: 1 # Since the headings are not read inside the collapsible block we can indent as 1
        output-format: asciidoc table
        output-file: README.adoc
        output-method: inject
        template: ${{ env.TABLES_TPL }}
        args: ${{ env.ARGS }}
        git-push: false

    # This step comes after long hours of debugging permission errors on the workflow when trying to do a commit after
    # executing the terraform-docs actions. See https://github.com/terraform-docs/gh-actions/issues/90
    - name: "Correct ownership of files in preparation for the next step"
      run: sudo chown runner:docker -Rv .git

    # This step avoids a commit for each previous step and instead commits everything on a single commit
    - name: "Commit changes done in the previous steps"
      uses: stefanzweifel/git-auto-commit-action@v5
      with:
        commit_message: "docs(terraform-docs): generate docs and write to README.adoc"