Resolve markdownlint warnings for READMEs

Author: dflook

README.md

@@ -8,6 +8,7 @@ These actions can be used to easily perform [Terraform](https://www.terraform.io
 Currently, there is just experimental support for OpenTofu, see [here](https://github.com/dflook/terraform-github-actions/blob/main/CHANGELOG.md#1370---2023-10-29)
 
 ## Actions
+
 See the documentation for the available actions:
 
 | Terraform                                                          | OpenTofu                                                |
@@ -28,6 +29,7 @@ See the documentation for the available actions:
 | [dflook/terraform-test](terraform-test)                            | [dflook/tofu-test](tofu-test)                           |
 
 ## Example Usage
+
 These actions can be added as steps to your own workflow files.
 GitHub reads workflow files from `.github/workflows/` within your repository.
 See the [Workflow documentation](https://docs.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow#about-workflows) for details on writing workflows.
@@ -42,15 +44,17 @@ Fortunately, GitHub has a well established method for requiring human reviews of
 We can use PRs to safely plan and apply infrastructure changes.
 
 <p align="center">
-    <img src="terraform-apply/planapply.gif" width="1000">
+    <img src="terraform-apply/planapply.gif" width="960" alt="A video showing a PR being created, a plan being generated, the plan being reviewed, and the plan being applied.">
 </p>
 
 You can make GitHub enforce this using branch protection, see the [dflook/terraform-apply](terraform-apply) action for details.
 
 In this example we use two workflows:
 
 #### plan.yaml
+
 This workflow runs on changes to a PR branch. It generates a Terraform plan and attaches it to the PR as a comment.
+
 ```yaml
 name: Create terraform plan
 
@@ -77,7 +81,9 @@ jobs:
 ```
 
 #### apply.yaml
+
 This workflow runs when the PR is merged into the main branch, and applies the planned changes.
+
 ```yaml
 name: Apply terraform plan
 
@@ -107,16 +113,18 @@ jobs:
 ```
 
 ### Linting
+
 This workflow runs on every push to non-main branches and checks the terraform configuration is valid.
 For extra strictness, we check the files are in the canonical format.
 
 <p align="center">
-    <img src="terraform-validate/validate.png" width="1000">
+    <img src="terraform-validate/validate.png" width="1000" alt="A screenshot showing the output of the terraform validate action.">
 </p>
 
 This can be used to check for correctness before merging.
 
 #### lint.yaml
+
 ```yaml
 name: Lint
 
@@ -159,6 +167,7 @@ This can be used to detect manual or misapplied changes before they become a pro
 If there are any unexpected changes, the workflow will fail.
 
 #### drift.yaml
+
 ```yaml
 name: Check for infrastructure drift
 
@@ -181,12 +190,14 @@ jobs:
 ```
 
 ### Scheduled infrastructure updates
+
 There may be times when you expect Terraform to plan updates without any changes to your configuration files.
 Your configuration could be consuming secrets from elsewhere, or renewing certificates every few months.
 
 This example workflow runs every morning and applies any outstanding changes to those specific resources.
 
 #### rotate-certs.yaml
+
 ```yaml
 name: Rotate TLS certificates
 
@@ -213,9 +224,11 @@ jobs:
 ```
 
 ### Automatically fixing formatting
+
 Perhaps you don't want to spend engineer time making formatting changes. This workflow will automatically create or update a PR that fixes any formatting issues.
 
 #### fmt.yaml
+
 ```yaml
 name: Check terraform file formatting
 
@@ -247,12 +260,14 @@ jobs:
 ```
 
 ### Ephemeral test environments
+
 Testing of software changes often requires some supporting infrastructure, like databases, DNS records, compute environments etc.
 We can use these actions to create dedicated resources for each PR which is used to run tests.
 
 There are two workflows:
 
 #### integration-test.yaml
+
 This workflow runs with every change to a PR.
 
 It deploys the testing infrastructure using a Terraform workspace dedicated to this branch, then runs integration tests against the new infrastructure.
@@ -290,7 +305,9 @@ jobs:
 ```
 
 #### integration-test-cleanup.yaml
+
 This workflow runs when a PR is closed and destroys any testing infrastructure that is no longer needed.
+
 ```yaml
 name: Destroy testing workspace
 

docs-gen/actions/apply.py

@@ -41,10 +41,12 @@
 You can instead set `auto_approve: true` which will generate a plan and apply it immediately, without looking for a plan attached to a PR.
 
 ## Demo
-This a demo of the process for apply a $ProductName change using the [`dflook/$ToolName-plan`](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-plan) and [`dflook/$ToolName-apply`](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-apply) actions.
+
+This a demo of the process for apply a $ProductName change using the [`dflook/$ToolName-plan`](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-plan)
+and [`dflook/$ToolName-apply`](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-apply) actions.
 
 <p align="center">
-    <img src="planapply.gif" width="1000">
+    <img src="planapply.gif" width="1000" alt="An example of the plan and apply actions">
 </p>
 
 ## GitHub
@@ -93,7 +95,7 @@
 
   - `apply-failed` - The Terraform apply operation failed.
   - `plan-changed` - The approved plan is no longer accurate, so the apply will not be attempted.
-  - `state-locked` - The Terraform state lock could not be obtained because it was already locked. 
+  - `state-locked` - The Terraform state lock could not be obtained because it was already locked.
 
   If the job fails for any other reason this will not be set.
   This can be used with the Actions expression syntax to conditionally run steps.
@@ -105,7 +107,7 @@
     ],
     environment_variables=[
         dataclasses.replace(GITHUB_TOKEN, description='''
-The GitHub authorization token to use to fetch an approved plan from a PR. 
+The GitHub authorization token to use to fetch an approved plan from a PR.
 This must belong to the same user/app as the token used by the [$ToolName-plan](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-plan) action.
         ''' + GITHUB_TOKEN.description),
         TERRAFORM_ACTIONS_GITHUB_TOKEN,
@@ -120,13 +122,13 @@
 
 When applying a plan from a PR comment (`auto_approve` is the default of `false`), the workflow can be triggered by the following events:
 
-  - pull_request
-  - pull_request_review_comment
-  - pull_request_target
-  - pull_request_review
-  - issue_comment, if the comment is on a PR (see below)
-  - push, if the pushed commit came from a PR (see below)
-  - repository_dispatch, if the client payload includes the pull_request url (see below)
+* pull_request
+* pull_request_review_comment
+* pull_request_target
+* pull_request_review
+* issue_comment, if the comment is on a PR (see below)
+* push, if the pushed commit came from a PR (see below)
+* repository_dispatch, if the client payload includes the pull_request url (see below)
 
 When `auto_approve` is set to `true`, the workflow can be triggered by any event.
 
@@ -165,6 +167,7 @@
 This event can be used to trigger a workflow from another workflow. The client payload must include the pull_request api url of where the plan PR comment can be found.
 
 A minimal example payload looks like:
+
 ```json
 {
   "pull_request": {

docs-gen/actions/destroy.py

@@ -22,7 +22,7 @@
     '''
     :warning: This action uses the `$ToolName destroy` command to immediately destroy all resources in a $ProductName workspace.
     
-    To generate a plan that can be reviewed you can instead use the [dflook/$ToolName-plan](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-plan) 
+    To generate a plan that can be reviewed you can instead use the [dflook/$ToolName-plan](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-plan)
     and [dflook/$ToolName-apply](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-plan) actions with the `destroy` input set to `true`.
     ''',
     meta_description='Destroys all resources in a $ProductName workspace',
@@ -41,7 +41,7 @@
           When the job outcome is `failure`, this output may be set. The value may be one of:
 
           - `destroy-failed` - The $ProductName destroy operation failed.
-          - `state-locked` - The $ProductName state lock could not be obtained because it was already locked. 
+          - `state-locked` - The $ProductName state lock could not be obtained because it was already locked.
 
           If the job fails for any other reason this will not be set.
           This can be used with the Actions expression syntax to conditionally run a steps.

docs-gen/actions/destroy_workspace.py

@@ -39,7 +39,7 @@
       When the job outcome is `failure`, this output may be set. The value may be one of:
 
       - `destroy-failed` - The $ProductName destroy operation failed.
-      - `state-locked` - The $ProductName state lock could not be obtained because it was already locked. 
+      - `state-locked` - The $ProductName state lock could not be obtained because it was already locked.
 
       If the job fails for any other reason this will not be set.
       This can be used with the Actions expression syntax to conditionally run a steps.

docs-gen/actions/fmt.py

@@ -17,15 +17,15 @@
     inputs=[
         dataclasses.replace(path, description='The path containing $ProductName files to format.'),
         dataclasses.replace(workspace, description='''
-            $ProductName workspace to inspect when discovering the $ProductName version to use, if the version is not otherwise specified. 
+            $ProductName workspace to inspect when discovering the $ProductName version to use, if the version is not otherwise specified.
             See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
         '''),
         dataclasses.replace(backend_config, description='''
-            List of $ProductName backend config values, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified. 
+            List of $ProductName backend config values, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified.
             See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
         '''),
         dataclasses.replace(backend_config_file, description='''
-            List of $ProductName backend config files to use, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified. 
+            List of $ProductName backend config files to use, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified.
             See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
             Paths should be relative to the GitHub Actions workspace
         ''')

docs-gen/actions/fmt_check.py

@@ -21,15 +21,15 @@
     inputs=[
         dataclasses.replace(path, description='The path containing $ProductName files to check the formatting of.'),
         dataclasses.replace(workspace, description='''
-            $ProductName workspace to inspect when discovering the $ProductName version to use, if the version is not otherwise specified. 
+            $ProductName workspace to inspect when discovering the $ProductName version to use, if the version is not otherwise specified.
             See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
         '''),
         dataclasses.replace(backend_config, description='''
-            List of $ProductName backend config values, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified. 
+            List of $ProductName backend config values, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified.
             See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
         '''),
         dataclasses.replace(backend_config_file, description='''
-            List of $ProductName backend config files to use, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified. 
+            List of $ProductName backend config files to use, one per line. This is used for discovering the $ProductName version to use, if the version is not otherwise specified.
             See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
             Paths should be relative to the GitHub Actions workspace
         ''')

docs-gen/actions/output.py

@@ -66,6 +66,7 @@
 This example gets information from object and array(object) outputs.
 
 With this $ProductName config:
+
 ```hcl
 output "vpc" {
   value = aws_vpc.test
@@ -76,6 +77,7 @@
 ```
 
 We can use the workflow:
+
 ```yaml
 jobs:
   output_example:
@@ -98,7 +100,8 @@
 ```
 
 Which will print to the workflow log:
-```
+
+```text
 The vpc-id is vpc-01463b6b84e1454ce
 The subnet-ids are subnet-053008016a2c1768c,subnet-07d4ce437c43eba2f,subnet-0a5f8c3a20023b8c0
 ```

docs-gen/actions/plan.py

@@ -36,7 +36,7 @@
 If the triggering event relates to a PR it will add a comment on the PR containing the generated plan.
 
 <p align="center">
-    <img src="plan.png" width="600">
+    <img src="plan.png" width="600" alt="An example of a PR comment created by the action">
 </p>
 
 The `GITHUB_TOKEN` environment variable must be set for the PR comment to be added.
@@ -87,13 +87,13 @@
 
 When adding the plan to a PR comment (`add_github_comment` is not `false`), the workflow can be triggered by the following events:
 
-  - pull_request
-  - pull_request_review_comment
-  - pull_request_target
-  - pull_request_review
-  - issue_comment, if the comment is on a PR (see below)
-  - push, if the pushed commit came from a PR (see below)
-  - repository_dispatch, if the client payload includes the pull_request url (see below)
+* pull_request
+* pull_request_review_comment
+* pull_request_target
+* pull_request_review
+* issue_comment, if the comment is on a PR (see below)
+* push, if the pushed commit came from a PR (see below)
+* repository_dispatch, if the client payload includes the pull_request url (see below)
 
 When `add_github_comment` is set to `false`, the workflow can be triggered by any event.
 
@@ -132,6 +132,7 @@
 This event can be used to trigger a workflow from another workflow. The client payload must include the pull_request api url of where the plan PR comment should be added.
 
 A minimal example payload looks like:
+
 ```json
 {
   "pull_request": {
@@ -175,10 +176,11 @@
 ### A full example of inputs
 
 This example workflow demonstrates most of the available inputs:
-- The environment variables are set at the workflow level.
-- The PR comment will be labelled `production`, and the plan will use the `prod` workspace.
-- Variables are read from `env/prod.tfvars`, with `turbo_mode` overridden to `true`.
-- The backend config is taken from `env/prod.backend`, and the token is set from a secret.
+
+* The environment variables are set at the workflow level.
+* The PR comment will be labelled `production`, and the plan will use the `prod` workspace.
+* Variables are read from `env/prod.tfvars`, with `turbo_mode` overridden to `true`.
+* The backend config is taken from `env/prod.backend`, and the token is set from a secret.
 
 ```yaml
 name: PR Plan

docs-gen/actions/validate.py

@@ -13,7 +13,7 @@
 from outputs.failure_reason import failure_reason
 
 backend_reason = '''
-This is used for discovering the $ProductName version to use, if not otherwise specified. 
+This is used for discovering the $ProductName version to use, if not otherwise specified.
 See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
 '''.strip()
 
@@ -26,7 +26,7 @@
     Failing GitHub checks will be added for any problems found.
     
     <p align="center">
-        <img src="validate.png" width="1000">
+        <img src="validate.png" width="1000" alt="An example of a failed validation check">
     </p>
     
     If the $ProductName configuration is not valid, the build is failed.
@@ -37,8 +37,8 @@
         dataclasses.replace(workspace, description='''
           $ProductName workspace to use for the `terraform.workspace` value while validating. Note that for remote operations in a cloud backend, this is always `default`.
 
-          Also used for discovering the $ProductName version to use, if not otherwise specified. 
-          See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details. 
+          Also used for discovering the $ProductName version to use, if not otherwise specified.
+          See [dflook/$ToolName-version](https://github.com/dflook/terraform-github-actions/tree/main/$ToolName-version#$ToolName-version-action) for details.
         '''),
         dataclasses.replace(backend_config, description=backend_config.description + backend_reason),
         dataclasses.replace(backend_config_file, description=backend_config_file.description + backend_reason),