Change default output-file to README.md

Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
terraform-docs · Feb 10, 2022 · 02fd9b4 · 02fd9b4
1 parent b70f26c
commit 02fd9b4
Show file tree

Hide file tree

Showing 12 changed files with 69 additions and 25 deletions.
diff --git a/.github/templates/README.tpl b/.github/templates/README.tpl
@@ -38,16 +38,19 @@ jobs:
       with:
         ref: {{"${{"}} github.event.pull_request.head.ref {{"}}"}}
 
-    - name: Render terraform docs inside the USAGE.md and push changes back to PR branch
+    - name: Render terraform docs inside the README.md and push changes back to PR branch
       uses: terraform-docs/gh-actions@{{ $version }}
       with:
         working-dir: .
-        output-file: USAGE.md
+        output-file: README.md
         output-method: inject
         git-push: "true"
 ```
 
-| 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. |
+| NOTE: If `output-file` (default README.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. |
+| --- |
+
+| NOTE: If `output-file` (default README.md) doesn't exist it will created and the content will be saved into it. |
 | --- |
 
 ## Configuration
@@ -131,7 +134,6 @@ To enable you need to ensure a few things first:
   uses: terraform-docs/gh-actions@{{ $version }}
   with:
     working-dir: .
-    output-file: README.md
 ```
 
 ### Multi folder
@@ -141,7 +143,6 @@ To enable you need to ensure a few things first:
   uses: terraform-docs/gh-actions@{{ $version }}
   with:
     working-dir: .,example1,example3/modules/test
-    output-file: README.md
 ```
 
 ### Use `atlantis.yaml` v3 to find all directories
@@ -162,6 +163,17 @@ To enable you need to ensure a few things first:
     find-dir: examples/
 ```
 
+### Recursively under a given directory
+
+```yaml
+- name: Generate TF docs
+  uses: terraform-docs/gh-actions@{{ $version }}
+  with:
+    working-dir: examples/
+    recursive: true
+    recursive-path: modules
+```
+
 Complete examples can be found [here](https://github.com/terraform-docs/gh-actions/tree/{{ $version }}/examples).
 
 [terraform-docs]: https://github.com/terraform-docs/terraform-docs
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -24,6 +24,7 @@ jobs:
         uses: ./
         with:
           working-dir: examples/tf11_basic
+          output-file: USAGE.md
           template: |-
             <!-- BEGIN_TF_DOCS -->
             # Test tf11 basic
@@ -44,6 +45,7 @@ jobs:
         with:
           working-dir: examples/tf11_extra_args
           output-format: markdown document
+          output-file: USAGE.md
           output-method: replace
           args: --sensitive=false --hide requirements --required=false
           indention: 3
@@ -52,41 +54,39 @@ jobs:
         uses: ./
         with:
           working-dir: examples/tf12_basic
-          output-file: README.md
           indention: 3
 
       - name: Should generate README.md for tf12_atlantis
         uses: ./
         with:
           atlantis-file: atlantis.yaml
-          output-file: README.md
           args: --hide providers
           indention: 3
 
-      - name: Should generate README.md for tf12_find and its submodules
+      - name: Should generate USAGE.md for tf12_find and its submodules
         uses: ./
         with:
           find-dir: examples/tf12_find
+          output-file: USAGE.md
 
-      - name: Should generate README.md for tf12_find and its submodules recursively
+      - name: Should generate USAGE.md for tf12_find and its submodules recursively
         uses: ./
         with:
           working-dir: examples/tf12_find
+          output-file: USAGE.md
           recursive: true
           recursive-path: modules
 
       - name: Should generate README.md for tf12_config
         uses: ./
         with:
           working-dir: examples/tf12_config
-          output-file: README.md
           config-file: .terraform-docs.yml
 
       - name: Should generate README.md for tf12_inject and push up all changes
         uses: ./
         with:
           working-dir: examples/tf12_inject
-          output-file: README.md
           args: --sort-by required
           indention: 3
           git-push: true
@@ -97,7 +97,6 @@ jobs:
         uses: ./
         with:
           working-dir: examples/tf12_fail_diff
-          output-file: README.md
           indention: 3
           fail-on-diff: true
 

diff --git a/README.md b/README.md
@@ -28,16 +28,19 @@ jobs:
       with:
         ref: ${{ github.event.pull_request.head.ref }}
 
-    - name: Render terraform docs inside the USAGE.md and push changes back to PR branch
+    - name: Render terraform docs inside the README.md and push changes back to PR branch
       uses: terraform-docs/gh-actions@v0.11.0
       with:
         working-dir: .
-        output-file: USAGE.md
+        output-file: README.md
         output-method: inject
         git-push: "true"
 ```
 
-| 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. |
+| NOTE: If `output-file` (default README.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. |
+| --- |
+
+| NOTE: If `output-file` (default README.md) doesn't exist it will created and the content will be saved into it. |
 | --- |
 
 ## Configuration
@@ -57,7 +60,7 @@ jobs:
 | git-push-user-email | If empty the no-reply email of the GitHub Actions bot will be used (i.e. `github-actions[bot]@users.noreply.github.com`) | `""` | false |
 | git-push-user-name | If empty the name of the GitHub Actions bot will be used (i.e. `github-actions[bot]`) | `""` | false |
 | indention | Indention level of Markdown sections [1, 2, 3, 4, 5] | `2` | false |
-| output-file | File in module directory where the docs should be placed | `USAGE.md` | false |
+| output-file | File in module directory where the docs should be placed | `README.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 |
 | recursive | If true it will update submodules recursively | `false` | false |
@@ -134,7 +137,6 @@ To enable you need to ensure a few things first:
   uses: terraform-docs/gh-actions@v0.11.0
   with:
     working-dir: .
-    output-file: README.md
 ```
 
 ### Multi folder
@@ -144,7 +146,6 @@ To enable you need to ensure a few things first:
   uses: terraform-docs/gh-actions@v0.11.0
   with:
     working-dir: .,example1,example3/modules/test
-    output-file: README.md
 ```
 
 ### Use `atlantis.yaml` v3 to find all directories
@@ -165,6 +166,17 @@ To enable you need to ensure a few things first:
     find-dir: examples/
 ```
 
+### Recursively under a given directory
+
+```yaml
+- name: Generate TF docs
+  uses: terraform-docs/gh-actions@v0.11.0
+  with:
+    working-dir: examples/
+    recursive: true
+    recursive-path: modules
+```
+
 Complete examples can be found [here](https://github.com/terraform-docs/gh-actions/tree/v0.11.0/examples).
 
 [terraform-docs]: https://github.com/terraform-docs/terraform-docs
diff --git a/action.yml b/action.yml
@@ -38,7 +38,7 @@ inputs:
   output-file:
     description: File in module directory where the docs should be placed
     required: false
-    default: "USAGE.md"
+    default: "README.md"
   template:
     description: When provided will be used as the template if/when the `output-file` does not exist
     default: |-

diff --git a/examples/tf11_basic/README.md b/examples/tf11_basic/README.md
@@ -7,6 +7,7 @@
   uses: ./
   with:
     working-dir: examples/tf11_basic
+    output-file: USAGE.md
     template: |-
       <!-- BEGIN_TF_DOCS -->
       # Test tf11 basic

diff --git a/examples/tf11_extra_args/README.md b/examples/tf11_extra_args/README.md
@@ -0,0 +1,24 @@
+# Test tf11 basic extra args
+
+## Input
+
+```yaml
+- name: Should generate USAGE.md for tf11_extra_args
+  uses: ./
+  with:
+    working-dir: examples/tf11_extra_args
+    output-format: markdown document
+    output-file: USAGE.md
+    output-method: replace
+    args: --sensitive=false --hide requirements --required=false
+    indention: 3
+```
+
+## Verify
+
+- Should not have requirements section
+- Should not have sensitive and required columns
+
+## Output
+
+See USAGE.md
diff --git a/examples/tf12_atlantis/README.md b/examples/tf12_atlantis/README.md
@@ -7,7 +7,6 @@
   uses: ./
   with:
     atlantis-file: atlantis.yaml
-    output-file: README.md
     args: --hide providers
     indention: 3
 ```

diff --git a/examples/tf12_basic/README.md b/examples/tf12_basic/README.md
@@ -7,7 +7,6 @@
   uses: ./
   with:
     working-dir: examples/tf12_basic
-    output-file: README.md
     indention: 3
 ```
 

diff --git a/examples/tf12_config/README.md b/examples/tf12_config/README.md
@@ -7,7 +7,6 @@
   uses: ./
   with:
     working-dir: examples/tf12_config
-    output-file: README.md
     config-file: .terraform-docs.yml
 ```
 

diff --git a/examples/tf12_fail_diff/README.md b/examples/tf12_fail_diff/README.md
@@ -7,7 +7,6 @@
   uses: ./
   with:
     working-dir: examples/tf12_fail_diff
-    output-file: README.md
     indention: 3
     fail-on-diff: true
 ```

diff --git a/examples/tf12_find/README.md b/examples/tf12_find/README.md
@@ -3,10 +3,11 @@
 ## Input
 
 ```yaml
-- name: Should generate README.md for tf12_find and its submodules
+- name: Should generate USAGE.md for tf12_find and its submodules
   uses: ./
   with:
     find-dir: examples/tf12_find
+    output-file: USAGE.md
 ```
 
 ## Verify

diff --git a/examples/tf12_inject/README.md b/examples/tf12_inject/README.md
@@ -7,7 +7,6 @@
   uses: ./
   with:
     working-dir: examples/tf12_inject
-    output-file: README.md
     args: --sort-by-required
     indention: 3
     git-push: true