Merge pull request #4 from johanneswuerbach/docs

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 = ""