feat: document sub modules (#11)

.pre-commit-config.yaml

@@ -25,24 +25,32 @@ repos:
 
       - id: terraform_validate
         name: Terraform validate
-        description: Validates all Terraform configuration files.
+        description: Validates root Terraform configuration files.
         entry: make validate
         language: system
         pass_filenames: false
         types: [terraform]
 
       - id: terraform_validate_submodules
         name: Terraform validate submodules
-        description: Validates all Terraform configuration files.
+        description: Validates submodule Terraform configuration files.
         entry: make validate-submodules
         language: system
         pass_filenames: false
         types: [terraform]
 
       - id: terraform_docs
-        name: Generate Docs
-        description: Generate terraform docs for module
+        name: Generate docs
+        description: Generate root terraform docs
         entry: make docs
         language: system
         pass_filenames: false
         types: [terraform]
+
+      - id: terraform_docs_submodules
+        name: Generate docs submodules
+        description: Generate submodule terraform docs
+        entry: make docs-submodules
+        language: system
+        pass_filenames: false
+        types: [terraform]

Makefile

@@ -7,7 +7,7 @@ SUBMODULES_PREFIX           := states
 export
 
 clean:
-	rm -rf **/.terraform
+	rm -rf ./**/.terraform*
 
 fmt:
 	docker run --rm --platform=linux/amd64 \
@@ -28,6 +28,18 @@ docs:
 		--output-mode inject \
 		/terraform-docs
 
+docs-submodules:
+	for submodule in ${SUBMODULES_PREFIX}/*; do\
+		echo "Generating docs for $${submodule}..."; \
+		docker run --rm --platform=linux/amd64 \
+			-v "$(CUR_DIR)/$${submodule}:/terraform-docs" \
+			quay.io/terraform-docs/terraform-docs:${TERRAFORM_DOCS_VERSION} markdown \
+			--output-file ./README.md \
+			--output-mode inject \
+			/terraform-docs; \
+	done
+
+
 init-no-backend:
 	docker run --rm --platform=linux/amd64 \
 		-v ${CUR_DIR}:/src \
@@ -43,7 +55,7 @@ validate: clean init-no-backend
 		-w /src \
 		hashicorp/terraform:${TERRAFORM_VERSION} validate
 
-validate-submodules:
+validate-submodules: clean
 	for submodule in ${SUBMODULES_PREFIX}/*; do\
 		echo "Validating $${submodule}..."; \
 		docker run --rm --platform=linux/amd64 \
@@ -57,4 +69,4 @@ validate-submodules:
 			-v ${CUR_DIR}:/src \
 			-w /src/$${submodule} \
 			hashicorp/terraform:${TERRAFORM_VERSION} validate; \
-    done
+	done

states/choice/README.md

@@ -0,0 +1,41 @@
+# choice state sub-module
+
+Terraform sub-module to provide an easy to use interface for creating AWS Step Function `Choice` states. The implementation obeys the interface described in the amazon-states-language documentation: 
+
+https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-choice-state.html
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+No modules.
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_choices"></a> [choices](#input\_choices) | An array of Choice Rules that determines which state the state machine transitions to next. | `list(any)` | n/a | yes |
+| <a name="input_comment"></a> [comment](#input\_comment) | A human-readable description of the state. | `string` | `null` | no |
+| <a name="input_default"></a> [default](#input\_default) | The name of the state to transition to if none of the transitions in Choices is taken. | `string` | `null` | no |
+| <a name="input_input_path"></a> [input\_path](#input\_input\_path) | A path that selects a portion of the state's input to be passed to the state's task for processing. | `string` | `null` | no |
+| <a name="input_name"></a> [name](#input\_name) | The name of the state object. | `string` | n/a | yes |
+| <a name="input_output_path"></a> [output\_path](#input\_output\_path) | A path that selects a portion of the state's output to be passed to the next state. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_definition"></a> [definition](#output\_definition) | The definition of the state |
+| <a name="output_name"></a> [name](#output\_name) | Name of the state |
+<!-- END_TF_DOCS -->

states/fail/README.md

@@ -0,0 +1,38 @@
+# fail state sub-module
+
+Terraform sub-module to provide an easy to use interface for creating AWS Step Function `Fail` states. The implementation obeys the interface described in the amazon-states-language documentation: 
+
+https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-fail-state.html
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+No modules.
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_cause"></a> [cause](#input\_cause) | A custom failure string that you can specify for operational or diagnostic purposes. | `string` | `null` | no |
+| <a name="input_error"></a> [error](#input\_error) | An error name that you can provide for operational or diagnostic purposes. | `string` | `null` | no |
+| <a name="input_name"></a> [name](#input\_name) | The name of the state object. | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_definition"></a> [definition](#output\_definition) | The definition of the state |
+| <a name="output_name"></a> [name](#output\_name) | Name of the state |
+<!-- END_TF_DOCS -->

states/map/README.md

@@ -0,0 +1,48 @@
+# map state sub-module
+
+Terraform sub-module to provide an easy to use interface for creating AWS Step Function `Map` states. The implementation obeys the interface described in the amazon-states-language documentation: 
+
+https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-map-state.html
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+No modules.
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_catch"></a> [catch](#input\_catch) | An array of objects, called Catchers, that define a fallback state. | `string` | `null` | no |
+| <a name="input_comment"></a> [comment](#input\_comment) | A human-readable description of the state. | `string` | `null` | no |
+| <a name="input_end"></a> [end](#input\_end) | Designates this state as a terminal state if set to true. | `bool` | `false` | no |
+| <a name="input_input_path"></a> [input\_path](#input\_input\_path) | A path that selects a portion of the state's input to be passed to the state's task for processing. | `string` | `null` | no |
+| <a name="input_items_path"></a> [items\_path](#input\_items\_path) | The ItemsPath field's value is a reference path identifying where in the effective input the array field is found. | `string` | `null` | no |
+| <a name="input_iterator"></a> [iterator](#input\_iterator) | The Iterator field's value is an object that defines a state machine which will process each element of the array. | `string` | n/a | yes |
+| <a name="input_max_concurrency"></a> [max\_concurrency](#input\_max\_concurrency) | The MaxConcurrencyfield's value is an integer that provides an upper bound on how many invocations of the Iterator may run in parallel. | `string` | `null` | no |
+| <a name="input_name"></a> [name](#input\_name) | The name of the state object. | `string` | n/a | yes |
+| <a name="input_next"></a> [next](#input\_next) | The name of the next state that is run when this state finishes. | `string` | `null` | no |
+| <a name="input_output_path"></a> [output\_path](#input\_output\_path) | A path that selects a portion of the state's output to be passed to the next state. | `string` | `null` | no |
+| <a name="input_result_path"></a> [result\_path](#input\_result\_path) | Specifies where to place the output (relative to the input) of the virtual task specified in Result. | `string` | `null` | no |
+| <a name="input_result_selector"></a> [result\_selector](#input\_result\_selector) | Pass a collection of key value pairs, where the values are static or selected from the result. | `string` | `null` | no |
+| <a name="input_retry"></a> [retry](#input\_retry) | An array of objects, called Retriers, that define a retry policy if the state encounters runtime errors. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_definition"></a> [definition](#output\_definition) | The definition of the state |
+| <a name="output_name"></a> [name](#output\_name) | Name of the state |
+<!-- END_TF_DOCS -->

states/parallel/README.md

@@ -0,0 +1,46 @@
+# parallel state sub-module
+
+Terraform sub-module to provide an easy to use interface for creating AWS Step Function `Parallel` states. The implementation obeys the interface described in the amazon-states-language documentation: 
+
+https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-parallel-state.html
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+No modules.
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_branches"></a> [branches](#input\_branches) | An array of objects that specify state machines to execute in parallel. | <pre>list(object({<br>    start_at = string<br>    states   = list(any)<br>  }))</pre> | n/a | yes |
+| <a name="input_catch"></a> [catch](#input\_catch) | An array of objects, called Catchers, that define a fallback state. | `string` | `null` | no |
+| <a name="input_comment"></a> [comment](#input\_comment) | A human-readable description of the state. | `string` | `null` | no |
+| <a name="input_end"></a> [end](#input\_end) | Designates this state as a terminal state if set to true. | `bool` | `false` | no |
+| <a name="input_input_path"></a> [input\_path](#input\_input\_path) | A path that selects a portion of the state's input to be passed to the state's task for processing. | `string` | `null` | no |
+| <a name="input_name"></a> [name](#input\_name) | The name of the state object. | `string` | n/a | yes |
+| <a name="input_next"></a> [next](#input\_next) | The name of the next state that is run when this state finishes. | `string` | `null` | no |
+| <a name="input_output_path"></a> [output\_path](#input\_output\_path) | A path that selects a portion of the state's output to be passed to the next state. | `string` | `null` | no |
+| <a name="input_result_path"></a> [result\_path](#input\_result\_path) | Specifies where to place the output (relative to the input) of the virtual task specified in Result. | `string` | `null` | no |
+| <a name="input_result_selector"></a> [result\_selector](#input\_result\_selector) | Pass a collection of key value pairs, where the values are static or selected from the result. | `string` | `null` | no |
+| <a name="input_retry"></a> [retry](#input\_retry) | An array of objects, called Retriers, that define a retry policy if the state encounters runtime errors. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_definition"></a> [definition](#output\_definition) | The definition of the state |
+| <a name="output_name"></a> [name](#output\_name) | Name of the state |
+<!-- END_TF_DOCS -->

states/pass/README.md

@@ -0,0 +1,44 @@
+# pass state sub-module
+
+Terraform sub-module to provide an easy to use interface for creating AWS Step Function `Pass` states. The implementation obeys the interface described in the amazon-states-language documentation: 
+
+https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-pass-state.html
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+No modules.
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_comment"></a> [comment](#input\_comment) | A human-readable description of the state. | `string` | `null` | no |
+| <a name="input_end"></a> [end](#input\_end) | Designates this state as a terminal state if set to true. | `bool` | `false` | no |
+| <a name="input_input_path"></a> [input\_path](#input\_input\_path) | A path that selects a portion of the state's input to be passed to the state's task for processing. | `string` | `null` | no |
+| <a name="input_name"></a> [name](#input\_name) | The name of the state object. | `string` | n/a | yes |
+| <a name="input_next"></a> [next](#input\_next) | The name of the next state that is run when this state finishes. | `string` | `null` | no |
+| <a name="input_output_path"></a> [output\_path](#input\_output\_path) | A path that selects a portion of the state's output to be passed to the next state. | `string` | `null` | no |
+| <a name="input_parameters"></a> [parameters](#input\_parameters) | Creates a collection of key-value pairs that will be passed as input. | `string` | `null` | no |
+| <a name="input_result"></a> [result](#input\_result) | Refers to the output of a virtual task that is passed on to the next state. | `string` | `null` | no |
+| <a name="input_result_path"></a> [result\_path](#input\_result\_path) | Specifies where to place the output (relative to the input) of the virtual task specified in Result. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_definition"></a> [definition](#output\_definition) | The definition of the state |
+| <a name="output_name"></a> [name](#output\_name) | Name of the state |
+<!-- END_TF_DOCS -->

states/succeed/README.md

@@ -0,0 +1,36 @@
+# succeed state sub-module
+
+Terraform sub-module to provide an easy to use interface for creating AWS Step Function `Succeed` states. The implementation obeys the interface described in the amazon-states-language documentation: 
+
+https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-succeed-state.html
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+No modules.
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_name"></a> [name](#input\_name) | The name of the state object. | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_definition"></a> [definition](#output\_definition) | The definition of the state |
+| <a name="output_name"></a> [name](#output\_name) | Name of the state |
+<!-- END_TF_DOCS -->

states/task/README.md

@@ -0,0 +1,51 @@
+# task state sub-module
+
+Terraform sub-module to provide an easy to use interface for creating AWS Step Function `Task` states. The implementation obeys the interface described in the amazon-states-language documentation: 
+
+https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-task-state.html
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+No providers.
+
+## Modules
+
+No modules.
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_catch"></a> [catch](#input\_catch) | An array of objects, called Catchers, that define a fallback state. | `string` | `null` | no |
+| <a name="input_comment"></a> [comment](#input\_comment) | A human-readable description of the state. | `string` | `null` | no |
+| <a name="input_end"></a> [end](#input\_end) | Designates this state as a terminal state if set to true. | `bool` | `false` | no |
+| <a name="input_heartbeat_seconds"></a> [heartbeat\_seconds](#input\_heartbeat\_seconds) | If more time than the specified seconds elapses between heartbeats from the task, this state fails with a States.Timeout error name. | `string` | `null` | no |
+| <a name="input_heartbeat_seconds_path"></a> [heartbeat\_seconds\_path](#input\_heartbeat\_seconds\_path) | If you want to provide a heartbeat value dynamically from the state input using a reference path, use HeartbeatSecondsPath. | `string` | `null` | no |
+| <a name="input_input_path"></a> [input\_path](#input\_input\_path) | A path that selects a portion of the state's input to be passed to the state's task for processing. | `string` | `null` | no |
+| <a name="input_name"></a> [name](#input\_name) | The name of the state object. | `string` | n/a | yes |
+| <a name="input_next"></a> [next](#input\_next) | The name of the next state that is run when this state finishes. | `string` | `null` | no |
+| <a name="input_output_path"></a> [output\_path](#input\_output\_path) | A path that selects a portion of the state's output to be passed to the next state. | `string` | `null` | no |
+| <a name="input_parameters"></a> [parameters](#input\_parameters) | Creates a collection of key-value pairs that will be passed as input. | `string` | `null` | no |
+| <a name="input_resource"></a> [resource](#input\_resource) | An ARN that uniquely identifies the specific task to execute. | `string` | n/a | yes |
+| <a name="input_result_path"></a> [result\_path](#input\_result\_path) | Specifies where to place the output (relative to the input) of the virtual task specified in Result. | `string` | `null` | no |
+| <a name="input_result_selector"></a> [result\_selector](#input\_result\_selector) | Pass a collection of key value pairs, where the values are static or selected from the result. | `string` | `null` | no |
+| <a name="input_retry"></a> [retry](#input\_retry) | An array of objects, called Retriers, that define a retry policy if the state encounters runtime errors. | `string` | `null` | no |
+| <a name="input_timeout_seconds"></a> [timeout\_seconds](#input\_timeout\_seconds) | If the task runs longer than the specified seconds, this state fails with a States.Timeout error name. | `string` | `null` | no |
+| <a name="input_timeout_seconds_path"></a> [timeout\_seconds\_path](#input\_timeout\_seconds\_path) | If you want to provide a timeout value dynamically from the state input using a reference path, use TimeoutSecondsPath. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_definition"></a> [definition](#output\_definition) | The definition of the state |
+| <a name="output_name"></a> [name](#output\_name) | Name of the state |
+<!-- END_TF_DOCS -->