chore: add docs target

.github/workflows/ci.yaml

@@ -9,10 +9,31 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
       - uses: hashicorp/setup-terraform@v2
         with:
           terraform_version: ~1.5
+
+      - name: Terraform Version
+        run: terraform -version
+
+      - name: Install terraform-docs
+        run: |
+          WORK_DIR=$(mktemp -d)
+          curl -Lo ${WORK_DIR}/terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.16.0/terraform-docs-v0.16.0-$(uname)-amd64.tar.gz
+          cd ${WORK_DIR}
+          tar -xzf terraform-docs.tar.gz
+          chmod +x terraform-docs
+          mv terraform-docs /usr/local/bin/terraform-docs
+
+      - name: Generate docs
+        run: make docs
+
+      - name: Check git diff is clean (all files generated should be committed)
+        run: git diff --exit-code
+
       - name: Terraform Format Check
         run: make fmt-check
+
       - name: Terraform Validate
         run: make validate

Makefile

@@ -1,5 +1,17 @@
 TF_DIRS = $(patsubst %/main.tf, %, $(shell find . -type d -name .terraform -prune -o -name 'main.tf' -print))
 VALIDATE_TF_DIRS = $(addprefix validate-,$(TF_DIRS))
+DOCS_TF_DIRS = $(addprefix docs-,$(TF_DIRS))
+
+# Generate docs for a terraform directories
+$(DOCS_TF_DIRS): docs-%:
+	@echo "Docs $*"
+	terraform-docs --config docs/.terraform-docs.yaml $*
+	terraform-docs --config docs/.terraform-docs-example.yaml $*
+
+# Generate docs
+.PHONY: docs
+docs: $(DOCS_TF_DIRS)
+	@echo "All docs generated"
 
 # Format all terraform files
 fmt:

README.md

@@ -10,9 +10,9 @@ A collection of in-cluster resources ready to be used with [Humanitec](https://h
 
 The following resources are included:
 
-* `mysql/basic`: A basic MySQL.
-* `postgres/basic`: A basic Postgres.
+* [mysql/basic](./humanitec-resource-defs/mysql/basic): A basic MySQL.
+* [postgres/basic](./humanitec-resource-defs/postgres/basic): A basic Postgres.
 
 The `humanitec-resource-defs` directory includes the respective resource definitions.
 
-Checkout `examples/main.tf` for an example using Postgres.
+Checkout `examples/postgres/main.tf` for an example using Postgres.

docs/.terraform-docs-example.yaml

@@ -0,0 +1,9 @@
+formatter: "tfvars hcl"
+
+output:
+  file: "./terraform.tfvars.example"
+  mode: replace
+  template: "{{ .Content }}"
+
+settings:
+  description: true

docs/.terraform-docs.yaml

@@ -0,0 +1,14 @@
+formatter: "markdown table"
+
+output:
+  file: "./README.md"
+
+sort:
+  enabled: true
+  by: required
+
+
+settings:
+  anchor: false
+  hide-empty: true
+  lockfile: false

examples/postgres/README.md

@@ -0,0 +1,21 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| postgres\_basic | ../../humanitec-resource-defs/postgres/basic | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_resource_definition_criteria.postgres_basic](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+<!-- END_TF_DOCS -->

examples/main.tf → examples/postgres/main.tf

@@ -6,7 +6,7 @@ locals {
 }
 
 module "postgres_basic" {
-  source = "../humanitec-resource-defs/postgres/basic"
+  source = "../../humanitec-resource-defs/postgres/basic"
 
   prefix = local.res_def_prefix
 }

humanitec-resource-defs/mysql/basic/README.md

@@ -0,0 +1,27 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_resource_definition.main](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| prefix | n/a | `string` | `""` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| id | n/a |
+<!-- END_TF_DOCS -->

humanitec-resource-defs/mysql/basic/terraform.tfvars.example

@@ -0,0 +1 @@
+prefix = ""

humanitec-resource-defs/postgres/basic/README.md

@@ -0,0 +1,27 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_resource_definition.main](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| prefix | n/a | `string` | `""` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| id | n/a |
+<!-- END_TF_DOCS -->

humanitec-resource-defs/postgres/basic/terraform.tfvars.example

@@ -0,0 +1 @@
+prefix = ""