From 02fd9b4361ef788dd198c3629409c5f206235c2f Mon Sep 17 00:00:00 2001 From: Khosrow Moossavi Date: Thu, 27 Jan 2022 15:11:56 -0500 Subject: [PATCH] Change default output-file to README.md Signed-off-by: Khosrow Moossavi --- .github/templates/README.tpl | 22 +++++++++++++++++----- .github/workflows/ci.yml | 13 ++++++------- README.md | 24 ++++++++++++++++++------ action.yml | 2 +- examples/tf11_basic/README.md | 1 + examples/tf11_extra_args/README.md | 24 ++++++++++++++++++++++++ examples/tf12_atlantis/README.md | 1 - examples/tf12_basic/README.md | 1 - examples/tf12_config/README.md | 1 - examples/tf12_fail_diff/README.md | 1 - examples/tf12_find/README.md | 3 ++- examples/tf12_inject/README.md | 1 - 12 files changed, 69 insertions(+), 25 deletions(-) create mode 100644 examples/tf11_extra_args/README.md diff --git a/.github/templates/README.tpl b/.github/templates/README.tpl index f570f84..9e6ed1b 100644 --- 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 `` and ``, 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 `` and ``, 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 index a010367..f64a5f6 100644 --- 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: |- # 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,26 +54,26 @@ 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 @@ -79,14 +81,12 @@ jobs: 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 index ac2960c..82633d9 100644 --- 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 `` and ``, 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 `` and ``, 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 index 07132f4..c7a9131 100644 --- 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 index 9854c1e..bfc32f9 100644 --- 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: |- # Test tf11 basic diff --git a/examples/tf11_extra_args/README.md b/examples/tf11_extra_args/README.md new file mode 100644 index 0000000..1f32bee --- /dev/null +++ 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 index 992fbf8..07b8ecd 100644 --- 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 index 9b19108..adb1a31 100644 --- 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 index b9665ce..7e56250 100644 --- 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 index 7fc5025..93c6447 100644 --- 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 index 79cc7d9..68e9589 100644 --- 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 index 4f83a8e..2f8f6dd 100644 --- 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