Use native output file, method, and template

Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
terraform-docs · Nov 24, 2021 · cb92e3d · cb92e3d
1 parent 36c9547
commit cb92e3d
Show file tree

Hide file tree

Showing 16 changed files with 186 additions and 264 deletions.
diff --git a/.github/templates/README.tpl b/.github/templates/README.tpl
@@ -1,5 +1,6 @@
 {{- define "escape_chars" }}{{ . | strings.ReplaceAll "_" "\\_" | strings.ReplaceAll "|" "\\|" | strings.ReplaceAll "*" "\\*" }}{{- end }}
 {{- define "sanatize_string" }}{{ . | strings.ReplaceAll "\n\n" "<br><br>" | strings.ReplaceAll "  \n" "<br>" | strings.ReplaceAll "\n" "<br>" | tmpl.Exec "escape_chars" }}{{- end }}
+{{- define "sanatize_value" }}{{ . | strings.ReplaceAll "\n\n" "\\n\\n" | strings.ReplaceAll "  \n" "\\n" | strings.ReplaceAll "\n" "\\n" }}{{- end }}
 {{- $action := (datasource "action") -}}
 {{- $version := or (getenv "VERSION") "main" -}}
 # terraform-docs GitHub Actions
@@ -46,7 +47,7 @@ jobs:
         git-push: "true"
 ```
 
-| WARNING: If USAGE.md already exists it will need to be updated, with the block delimeters `<!--- BEGIN_TF_DOCS --->` and `<!--- END_TF_DOCS --->`, where the generated markdown will be injected. |
+| NOTE: If USAGE.md already exists it will need to be updated, with the block delimeters `<!-- BEGIN_TF_DOCS -->` and `<!-- END_TF_DOCS -->`, where the generated markdown will be injected. Otherwise the generated content will be appended at the end of the file. |
 | --- |
 
 ## Configuration
@@ -56,7 +57,7 @@ jobs:
 | Name | Description | Default | Required |
 |------|-------------|---------|----------|
 {{- range $key, $input := $action.inputs }}
-| {{ tmpl.Exec "escape_chars" $key }} | {{ if (has $input "description") }}{{ tmpl.Exec "sanatize_string" $input.description }}{{ else }}{{ tmpl.Exec "escape_chars" $key }}{{ end }} | {{ if (has $input "default") }}`{{ if $input.default }}{{ tmpl.Exec "sanatize_string" $input.default }}{{ else }}""{{ end }}`{{ else }}N/A{{ end }} | {{ if (has $input "required") }}{{ $input.required }}{{ else }}false{{ end }} |
+| {{ tmpl.Exec "escape_chars" $key }} | {{ if (has $input "description") }}{{ tmpl.Exec "sanatize_string" $input.description }}{{ else }}{{ tmpl.Exec "escape_chars" $key }}{{ end }} | {{ if (has $input "default") }}`{{ if $input.default }}{{ tmpl.Exec "sanatize_value" $input.default }}{{ else }}""{{ end }}`{{ else }}N/A{{ end }} | {{ if (has $input "required") }}{{ $input.required }}{{ else }}false{{ end }} |
 {{- end }}
 
 #### Output Method (output-method)
@@ -72,10 +73,10 @@ jobs:
 - `inject`
 
   Instead of replacing the `output-file`, this will inject the generated documentation
-  into the existing file between the predefined delimeters: `<!--- BEGIN_TF_DOCS --->`
-  and `<!--- END_TF_DOCS --->`. If the file exists but does not contain the delimeters,
-  the action will fail for the given module. If the file doesn't exist, it will create
-  it using the value template which MUST have the delimeters.
+  into the existing file between the predefined delimeters: `<!-- BEGIN_TF_DOCS -->`
+  and `<!-- END_TF_DOCS -->`. If the file exists but does not contain the delimeters,
+  the action will append the generated content at the end of `output-file`. If the file
+  doesn't exist, it will create it using the value template which MUST have the delimeters.
 
 #### Auto commit changes
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,8 +12,8 @@ jobs:
         uses: actions/checkout@v2
         with:
           fetch-depth: 0
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
 
       - name: Build Docker image
         run: |
@@ -24,7 +24,8 @@ jobs:
         uses: ./
         with:
           working-dir: examples/tf11_basic
-          template: |
+          template: |-
+            <!-- BEGIN_TF_DOCS -->
             # Test tf11 basic
 
             ## Verify
@@ -34,8 +35,8 @@ jobs:
 
             # Usage
 
-            <!--- BEGIN_TF_DOCS --->
-            <!--- END_TF_DOCS --->
+            {{ .Content }}
+            <!-- END_TF_DOCS -->
           indention: 3
 
       - name: Should generate USAGE.md for tf11_extra_args
@@ -74,13 +75,6 @@ jobs:
           output-file: README.md
           config-file: .terraform-docs.yml
 
-      - name: Should generate README.md for tf12_fail_diff
-        uses: ./
-        with:
-          working-dir: examples/tf12_fail_diff
-          output-file: README.md
-          indention: 3
-
       - name: Should generate README.md for tf12_inject and push up all changes
         uses: ./
         with:

diff --git a/README.md b/README.md
@@ -37,7 +37,7 @@ jobs:
         git-push: "true"
 ```
 
-| WARNING: If USAGE.md already exists it will need to be updated, with the block delimeters `<!--- BEGIN_TF_DOCS --->` and `<!--- END_TF_DOCS --->`, where the generated markdown will be injected. |
+| NOTE: If USAGE.md already exists it will need to be updated, with the block delimeters `<!-- BEGIN_TF_DOCS -->` and `<!-- END_TF_DOCS -->`, where the generated markdown will be injected. Otherwise the generated content will be appended at the end of the file. |
 | --- |
 
 ## Configuration
@@ -60,7 +60,7 @@ jobs:
 | output-file | File in module directory where the docs should be placed | `USAGE.md` | false |
 | output-format | terraform-docs format to generate content (see [all formats](https://github.com/terraform-docs/terraform-docs/blob/master/docs/FORMATS\_GUIDE.md)) (ignored if `config-file` is set) | `markdown table` | false |
 | output-method | Method should be one of `replace`, `inject`, or `print` | `inject` | false |
-| template | When provided will be used as the template if/when the `output-file` does not exist | `# Usage<br><br><!--- BEGIN\_TF\_DOCS ---><br><!--- END\_TF\_DOCS ---><br>` | false |
+| template | When provided will be used as the template if/when the `output-file` does not exist | `<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->` | false |
 | working-dir | Comma separated list of directories to generate docs for (ignored if `atlantis-file` or `find-dir` is set) | `.` | false |
 
 #### Output Method (output-method)
@@ -76,10 +76,10 @@ jobs:
 - `inject`
 
   Instead of replacing the `output-file`, this will inject the generated documentation
-  into the existing file between the predefined delimeters: `<!--- BEGIN_TF_DOCS --->`
-  and `<!--- END_TF_DOCS --->`. If the file exists but does not contain the delimeters,
-  the action will fail for the given module. If the file doesn't exist, it will create
-  it using the value template which MUST have the delimeters.
+  into the existing file between the predefined delimeters: `<!-- BEGIN_TF_DOCS -->`
+  and `<!-- END_TF_DOCS -->`. If the file exists but does not contain the delimeters,
+  the action will append the generated content at the end of `output-file`. If the file
+  doesn't exist, it will create it using the value template which MUST have the delimeters.
 
 #### Auto commit changes
 

diff --git a/action.yml b/action.yml
@@ -33,11 +33,10 @@ inputs:
     default: "USAGE.md"
   template:
     description: When provided will be used as the template if/when the `output-file` does not exist
-    default: |
-      # Usage
-
-      <!--- BEGIN_TF_DOCS --->
-      <!--- END_TF_DOCS --->
+    default: |-
+      <!-- BEGIN_TF_DOCS -->
+      {{ .Content }}
+      <!-- END_TF_DOCS -->
     required: false
   args:
     description: Additional arguments to pass to the command (see [full documentation](https://github.com/terraform-docs/terraform-docs/tree/master/docs))

diff --git a/examples/tf11_basic/README.md b/examples/tf11_basic/README.md
@@ -7,7 +7,8 @@
   uses: ./
   with:
     working-dir: examples/tf11_basic
-    template: |
+    template: |-
+      <!-- BEGIN_TF_DOCS -->
       # Test tf11 basic
 
       ## Verify
@@ -17,8 +18,8 @@
 
       # Usage
 
-      <!--- BEGIN_TF_DOCS --->
-      <!--- END_TF_DOCS --->
+      {{ .Content }}
+      <!-- END_TF_DOCS -->
     indention: 3
 ```
 

diff --git a/examples/tf11_basic/USAGE.md b/examples/tf11_basic/USAGE.md
@@ -1,13 +1,13 @@
-# Test tf11 basic
-
-## Verify
-
-Should use the template defined instead of the default
-Should inject the table under usage
-
-## Usage
-
-<!--- BEGIN_TF_DOCS --->
+<!-- BEGIN_TF_DOCS -->
+# Test tf11 basic
+
+## Verify
+
+Should use the template defined instead of the default
+Should inject the table under usage
+
+# Usage
+
 ### Requirements
 
 | Name | Version |
@@ -49,5 +49,4 @@ No modules.
 | Name | Description |
 |------|-------------|
 | <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | The Id of the VPC |
-
-<!--- END_TF_DOCS --->
+<!-- END_TF_DOCS -->
diff --git a/examples/tf11_extra_args/README.md b/examples/tf11_extra_args/README.md
diff --git a/examples/tf11_extra_args/USAGE.md b/examples/tf11_extra_args/USAGE.md
@@ -1,6 +1,4 @@
-# Usage
-
-<!--- BEGIN_TF_DOCS --->
+<!-- BEGIN_TF_DOCS -->
 ### Providers
 
 The following providers are used by this module:
@@ -79,6 +77,4 @@ The following outputs are exported:
 #### <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id)
 
 Description: The Id of the VPC
-
-<!--- END_TF_DOCS --->
-
+<!-- END_TF_DOCS -->
diff --git a/examples/tf12_atlantis/README.md b/examples/tf12_atlantis/README.md
@@ -1,25 +1,25 @@
-# Test tf12 Atlantis
-
-## Input
-
-```yaml
-- name: Should generate README.md for tf12_atlantis
-  uses: ./
-  with:
-    atlantis-file: atlantis.yaml
-    output-file: README.md
-    args: --hide providers
-    indention: 3
-```
-
-## Verify
-
-- Should inject below Usage in README.md
-- Should not show providers section
-
-## Usage
-
-<!--- BEGIN_TF_DOCS --->
+# Test tf12 Atlantis
+
+## Input
+
+```yaml
+- name: Should generate README.md for tf12_atlantis
+  uses: ./
+  with:
+    atlantis-file: atlantis.yaml
+    output-file: README.md
+    args: --hide providers
+    indention: 3
+```
+
+## Verify
+
+- Should inject below Usage in README.md
+- Should not show providers section
+
+## Usage
+
+<!-- BEGIN_TF_DOCS -->
 ### Requirements
 
 | Name | Version |
@@ -54,5 +54,4 @@ No modules.
 | Name | Description |
 |------|-------------|
 | <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | The Id of the VPC |
-
-<!--- END_TF_DOCS --->
+<!-- END_TF_DOCS -->
diff --git a/examples/tf12_basic/README.md b/examples/tf12_basic/README.md
@@ -1,23 +1,23 @@
-# Test tf12 basic
-
-## Input
-
-```yaml
-- name: Should generate README.md for tf12_bsic
-  uses: ./
-  with:
-    working-dir: examples/tf12_basic
-    output-file: README.md
-    indention: 3
-```
-
-## Verify
-
-- Should inject below Usage in README.md
-
-## Usage
-
-<!--- BEGIN_TF_DOCS --->
+# Test tf12 basic
+
+## Input
+
+```yaml
+- name: Should generate README.md for tf12_bsic
+  uses: ./
+  with:
+    working-dir: examples/tf12_basic
+    output-file: README.md
+    indention: 3
+```
+
+## Verify
+
+- Should inject below Usage in README.md
+
+## Usage
+
+<!-- BEGIN_TF_DOCS -->
 ### Requirements
 
 | Name | Version |
@@ -59,5 +59,4 @@ No modules.
 | Name | Description |
 |------|-------------|
 | <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | The Id of the VPC |
-
-<!--- END_TF_DOCS --->
+<!-- END_TF_DOCS -->