Skip to content

Commit b12db61

Browse files
khos2owkhos2ow
authored
Merge pull request #46 from khos2ow/native-output-file
Use native output file, method, and template
2 parents 36c9547 + cb92e3d commit b12db61

File tree

16 files changed

+186
-264
lines changed

16 files changed

+186
-264
lines changed

‎.github/templates/README.tpl

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{{- define "escape_chars" }}{{ . | strings.ReplaceAll "_" "\\_" | strings.ReplaceAll "|" "\\|" | strings.ReplaceAll "*" "\\*" }}{{- end }}
22
{{- define "sanatize_string" }}{{ . | strings.ReplaceAll "\n\n" "<br><br>" | strings.ReplaceAll " \n" "<br>" | strings.ReplaceAll "\n" "<br>" | tmpl.Exec "escape_chars" }}{{- end }}
3+
{{- define "sanatize_value" }}{{ . | strings.ReplaceAll "\n\n" "\\n\\n" | strings.ReplaceAll " \n" "\\n" | strings.ReplaceAll "\n" "\\n" }}{{- end }}
34
{{- $action := (datasource "action") -}}
45
{{- $version := or (getenv "VERSION") "main" -}}
56
# terraform-docs GitHub Actions
@@ -46,7 +47,7 @@ jobs:
4647
git-push: "true"
4748
```
4849

49-
| 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. |
50+
| 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. |
5051
| --- |
5152

5253
## Configuration
@@ -56,7 +57,7 @@ jobs:
5657
| Name | Description | Default | Required |
5758
|------|-------------|---------|----------|
5859
{{- range $key, $input := $action.inputs }}
59-
| {{ 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 }} |
60+
| {{ 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 }} |
6061
{{- end }}
6162

6263
#### Output Method (output-method)
@@ -72,10 +73,10 @@ jobs:
7273
- `inject`
7374

7475
Instead of replacing the `output-file`, this will inject the generated documentation
75-
into the existing file between the predefined delimeters: `<!--- BEGIN_TF_DOCS --->`
76-
and `<!--- END_TF_DOCS --->`. If the file exists but does not contain the delimeters,
77-
the action will fail for the given module. If the file doesn't exist, it will create
78-
it using the value template which MUST have the delimeters.
76+
into the existing file between the predefined delimeters: `<!-- BEGIN_TF_DOCS -->`
77+
and `<!-- END_TF_DOCS -->`. If the file exists but does not contain the delimeters,
78+
the action will append the generated content at the end of `output-file`. If the file
79+
doesn't exist, it will create it using the value template which MUST have the delimeters.
7980

8081
#### Auto commit changes
8182

‎.github/workflows/ci.yml

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ jobs:
1212
uses: actions/checkout@v2
1313
with:
1414
fetch-depth: 0
15-
ref: ${{github.event.pull_request.head.ref}}
16-
repository: ${{github.event.pull_request.head.repo.full_name}}
15+
ref: ${{ github.event.pull_request.head.ref }}
16+
repository: ${{ github.event.pull_request.head.repo.full_name }}
1717

1818
- name: Build Docker image
1919
run: |
@@ -24,7 +24,8 @@ jobs:
2424
uses: ./
2525
with:
2626
working-dir: examples/tf11_basic
27-
template: |
27+
template: |-
28+
<!-- BEGIN_TF_DOCS -->
2829
# Test tf11 basic
2930
3031
## Verify
@@ -34,8 +35,8 @@ jobs:
3435
3536
# Usage
3637
37-
<!--- BEGIN_TF_DOCS --->
38-
<!--- END_TF_DOCS --->
38+
{{ .Content }}
39+
<!-- END_TF_DOCS -->
3940
indention: 3
4041

4142
- name: Should generate USAGE.md for tf11_extra_args
@@ -74,13 +75,6 @@ jobs:
7475
output-file: README.md
7576
config-file: .terraform-docs.yml
7677

77-
- name: Should generate README.md for tf12_fail_diff
78-
uses: ./
79-
with:
80-
working-dir: examples/tf12_fail_diff
81-
output-file: README.md
82-
indention: 3
83-
8478
- name: Should generate README.md for tf12_inject and push up all changes
8579
uses: ./
8680
with:

‎README.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ jobs:
3737
git-push: "true"
3838
```
3939
40-
| 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. |
40+
| 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. |
4141
| --- |
4242

4343
## Configuration
@@ -60,7 +60,7 @@ jobs:
6060
| output-file | File in module directory where the docs should be placed | `USAGE.md` | false |
6161
| 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 |
6262
| output-method | Method should be one of `replace`, `inject`, or `print` | `inject` | false |
63-
| 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 |
63+
| 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 |
6464
| working-dir | Comma separated list of directories to generate docs for (ignored if `atlantis-file` or `find-dir` is set) | `.` | false |
6565

6666
#### Output Method (output-method)
@@ -76,10 +76,10 @@ jobs:
7676
- `inject`
7777

7878
Instead of replacing the `output-file`, this will inject the generated documentation
79-
into the existing file between the predefined delimeters: `<!--- BEGIN_TF_DOCS --->`
80-
and `<!--- END_TF_DOCS --->`. If the file exists but does not contain the delimeters,
81-
the action will fail for the given module. If the file doesn't exist, it will create
82-
it using the value template which MUST have the delimeters.
79+
into the existing file between the predefined delimeters: `<!-- BEGIN_TF_DOCS -->`
80+
and `<!-- END_TF_DOCS -->`. If the file exists but does not contain the delimeters,
81+
the action will append the generated content at the end of `output-file`. If the file
82+
doesn't exist, it will create it using the value template which MUST have the delimeters.
8383

8484
#### Auto commit changes
8585

‎action.yml

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,10 @@ inputs:
3333
default: "USAGE.md"
3434
template:
3535
description: When provided will be used as the template if/when the `output-file` does not exist
36-
default: |
37-
# Usage
38-
39-
<!--- BEGIN_TF_DOCS --->
40-
<!--- END_TF_DOCS --->
36+
default: |-
37+
<!-- BEGIN_TF_DOCS -->
38+
{{ .Content }}
39+
<!-- END_TF_DOCS -->
4140
required: false
4241
args:
4342
description: Additional arguments to pass to the command (see [full documentation](https://github.com/terraform-docs/terraform-docs/tree/master/docs))

‎examples/tf11_basic/README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
uses: ./
88
with:
99
working-dir: examples/tf11_basic
10-
template: |
10+
template: |-
11+
<!-- BEGIN_TF_DOCS -->
1112
# Test tf11 basic
1213
1314
## Verify
@@ -17,8 +18,8 @@
1718
1819
# Usage
1920
20-
<!--- BEGIN_TF_DOCS --->
21-
<!--- END_TF_DOCS --->
21+
{{ .Content }}
22+
<!-- END_TF_DOCS -->
2223
indention: 3
2324
```
2425

‎examples/tf11_basic/USAGE.md

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
# Test tf11 basic
2-
3-
## Verify
4-
5-
Should use the template defined instead of the default
6-
Should inject the table under usage
7-
8-
## Usage
9-
10-
<!--- BEGIN_TF_DOCS --->
1+
<!-- BEGIN_TF_DOCS -->
2+
# Test tf11 basic
3+
4+
## Verify
5+
6+
Should use the template defined instead of the default
7+
Should inject the table under usage
8+
9+
# Usage
10+
1111
### Requirements
1212

1313
| Name | Version |
@@ -49,5 +49,4 @@ No modules.
4949
| Name | Description |
5050
|------|-------------|
5151
| <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | The Id of the VPC |
52-
53-
<!--- END_TF_DOCS --->
52+
<!-- END_TF_DOCS -->

‎examples/tf11_extra_args/README.md

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎examples/tf11_extra_args/USAGE.md

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
# Usage
2-
3-
<!--- BEGIN_TF_DOCS --->
1+
<!-- BEGIN_TF_DOCS -->
42
### Providers
53

64
The following providers are used by this module:
@@ -79,6 +77,4 @@ The following outputs are exported:
7977
#### <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id)
8078

8179
Description: The Id of the VPC
82-
83-
<!--- END_TF_DOCS --->
84-
80+
<!-- END_TF_DOCS -->

‎examples/tf12_atlantis/README.md

Lines changed: 23 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,25 @@
1-
# Test tf12 Atlantis
2-
3-
## Input
4-
5-
```yaml
6-
- name: Should generate README.md for tf12_atlantis
7-
uses: ./
8-
with:
9-
atlantis-file: atlantis.yaml
10-
output-file: README.md
11-
args: --hide providers
12-
indention: 3
13-
```
14-
15-
## Verify
16-
17-
- Should inject below Usage in README.md
18-
- Should not show providers section
19-
20-
## Usage
21-
22-
<!--- BEGIN_TF_DOCS --->
1+
# Test tf12 Atlantis
2+
3+
## Input
4+
5+
```yaml
6+
- name: Should generate README.md for tf12_atlantis
7+
uses: ./
8+
with:
9+
atlantis-file: atlantis.yaml
10+
output-file: README.md
11+
args: --hide providers
12+
indention: 3
13+
```
14+
15+
## Verify
16+
17+
- Should inject below Usage in README.md
18+
- Should not show providers section
19+
20+
## Usage
21+
22+
<!-- BEGIN_TF_DOCS -->
2323
### Requirements
2424
2525
| Name | Version |
@@ -54,5 +54,4 @@ No modules.
5454
| Name | Description |
5555
|------|-------------|
5656
| <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | The Id of the VPC |
57-
58-
<!--- END_TF_DOCS --->
57+
<!-- END_TF_DOCS -->

‎examples/tf12_basic/README.md

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
1-
# Test tf12 basic
2-
3-
## Input
4-
5-
```yaml
6-
- name: Should generate README.md for tf12_bsic
7-
uses: ./
8-
with:
9-
working-dir: examples/tf12_basic
10-
output-file: README.md
11-
indention: 3
12-
```
13-
14-
## Verify
15-
16-
- Should inject below Usage in README.md
17-
18-
## Usage
19-
20-
<!--- BEGIN_TF_DOCS --->
1+
# Test tf12 basic
2+
3+
## Input
4+
5+
```yaml
6+
- name: Should generate README.md for tf12_bsic
7+
uses: ./
8+
with:
9+
working-dir: examples/tf12_basic
10+
output-file: README.md
11+
indention: 3
12+
```
13+
14+
## Verify
15+
16+
- Should inject below Usage in README.md
17+
18+
## Usage
19+
20+
<!-- BEGIN_TF_DOCS -->
2121
### Requirements
2222
2323
| Name | Version |
@@ -59,5 +59,4 @@ No modules.
5959
| Name | Description |
6060
|------|-------------|
6161
| <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | The Id of the VPC |
62-
63-
<!--- END_TF_DOCS --->
62+
<!-- END_TF_DOCS -->

0 commit comments

Comments
 (0)