From da139e3515b636596b35c460262f2176ae50fd6a Mon Sep 17 00:00:00 2001 From: Jon M Date: Tue, 19 Dec 2023 15:53:36 +0000 Subject: [PATCH 1/9] set up for testing - revert later set-up for test with no README remove lock file - not needed set-up to test adding to existing README restore README to original --- .pre-commit-config.yaml | 14 ++++++++++++++ outputs.tf | 4 ++++ 2 files changed, 18 insertions(+) create mode 100644 outputs.tf diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 17fc5a6fc..b12ec6e1f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -58,3 +58,17 @@ repos: - id: prettier # https://prettier.io/docs/en/options.html#parser files: '.json5$' + + +- repo: local + hooks: + - id: terraform_docs + name: terraform_docs + entry: ./hooks/terraform_docs.sh + args: + - --hook-config=--path-to-file=README.md + - --hook-config=--use_standard_markers=false + - --hook-config=--create-file-if-not-exist=true + - --hook-config=--add-to-existing-file=true + language: system + files: (\.tf)$ diff --git a/outputs.tf b/outputs.tf new file mode 100644 index 000000000..a3319169a --- /dev/null +++ b/outputs.tf @@ -0,0 +1,4 @@ +output "api_address" { + value = aws_api_gateway_stage.default_audit_stream.invoke_url + description = "Invoke URL for the API" +} From 2689898420fed0fba27c551f467d6c8cdae0db09 Mon Sep 17 00:00:00 2001 From: Jon M Date: Wed, 20 Dec 2023 11:38:22 +0000 Subject: [PATCH 2/9] parse new argument "use_standard_markers" WIP struggling with bash variable scope refactor perl command to allow variable expansion working hook, needs tidy up --- hooks/terraform_docs.sh | 54 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/hooks/terraform_docs.sh b/hooks/terraform_docs.sh index c994208f7..42b0ceb15 100755 --- a/hooks/terraform_docs.sh +++ b/hooks/terraform_docs.sh @@ -7,6 +7,11 @@ readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)" # shellcheck source=_common.sh . "$SCRIPT_DIR/_common.sh" +# set up default insertion markers. These will be changed to the markers used by +# terraform-docs if the hook config contains `--use_standard_markers=true` +insertion_marker_begin="" +insertion_marker_end="" + function main { common::initialize "$SCRIPT_DIR" common::parse_cmdline "$@" @@ -37,6 +42,34 @@ function terraform_docs_ { # Get hook settings IFS=";" read -r -a configs <<< "$hook_config" + # Variable to store the standard markers argument + use_standard_markers=false + + # Iterate through the array + for arg in "${configs[@]}"; do + # remove leading whitespace characters + arg="${arg#"${arg%%[![:space:]]*}"}" + # Check if the argument starts with 'use_standard_markers=' + if [[ $arg == '--use_standard_markers='* ]]; then + # Extract the value after '=' and store it in the use_standard_markers variable + use_standard_markers="${arg#*=}" + + # Remove the argument from the array + configs=("${configs[@]/$arg/}") + + # Break out of the loop since argument has been found + break + fi + done + + echo "Use standard markers: $use_standard_markers" + echo "Remaining hook config: ${configs[@]}" + + if [ "$use_standard_markers" = true ] ; then + insertion_marker_begin="" + insertion_marker_end="" + fi + local hack_terraform_docs hack_terraform_docs=$(terraform version | sed -n 1p | grep -c 0.12) || true @@ -178,10 +211,13 @@ function terraform_docs { dir="$(dirname "$text_file")" mkdir -p "$dir" + + echo "FIRST USE: $insertion_marker_begin (NO README)" + { echo -e "# ${PWD##*/}\n" - echo "" - echo "" + echo $insertion_marker_begin + echo $insertion_marker_end } >> "$text_file" fi @@ -193,11 +229,13 @@ function terraform_docs { # and if not - append "hook markers" to the end of file. # if $add_to_existing; then - HAVE_MARKER=$(grep -o '' "$text_file" || exit 0) + HAVE_MARKER=$(grep -o "$insertion_marker_begin" "$text_file" || exit 0) if [ ! "$HAVE_MARKER" ]; then - echo "" >> "$text_file" - echo "" >> "$text_file" + echo "SECOND USE: $insertion_marker_begin (addToExisting with no marker in file)" + + echo $insertion_marker_begin >> "$text_file" + echo $insertion_marker_end >> "$text_file" fi fi @@ -218,8 +256,12 @@ function terraform_docs { rm -f "$tmp_file_docs_tf" fi + echo "THIRD USE: $insertion_marker_begin (UPDATE DOC)" + # Replace content between markers with the placeholder - https://stackoverflow.com/questions/1212799/how-do-i-extract-lines-between-two-line-delimiters-in-perl#1212834 - perl -i -ne 'if (/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/../END OF PRE-COMMIT-TERRAFORM DOCS HOOK/) { print $_ if /BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/; print "I_WANT_TO_BE_REPLACED\n$_" if /END OF PRE-COMMIT-TERRAFORM DOCS HOOK/;} else { print $_ }' "$text_file" + perl_expression="if (/$insertion_marker_begin/../$insertion_marker_end/) { print \$_ if /$insertion_marker_begin/; print \"I_WANT_TO_BE_REPLACED\\n\$_\" if /$insertion_marker_end/;} else { print \$_ }" + perl -i -ne "$perl_expression" "$text_file" + echo "$perl_expression" # Replace placeholder with the content of the file perl -i -e 'open(F, "'"$tmp_file"'"); $f = join "", ; while(<>){if (/I_WANT_TO_BE_REPLACED/) {print $f} else {print $_};}' "$text_file" From fd91685002217d2264b5745e326a0b1bc9f10799 Mon Sep 17 00:00:00 2001 From: Jon M Date: Wed, 20 Dec 2023 16:25:46 +0000 Subject: [PATCH 3/9] Revert "set up for testing - revert later" This reverts commit da139e3515b636596b35c460262f2176ae50fd6a. --- .pre-commit-config.yaml | 14 -------------- outputs.tf | 4 ---- 2 files changed, 18 deletions(-) delete mode 100644 outputs.tf diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b12ec6e1f..17fc5a6fc 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -58,17 +58,3 @@ repos: - id: prettier # https://prettier.io/docs/en/options.html#parser files: '.json5$' - - -- repo: local - hooks: - - id: terraform_docs - name: terraform_docs - entry: ./hooks/terraform_docs.sh - args: - - --hook-config=--path-to-file=README.md - - --hook-config=--use_standard_markers=false - - --hook-config=--create-file-if-not-exist=true - - --hook-config=--add-to-existing-file=true - language: system - files: (\.tf)$ diff --git a/outputs.tf b/outputs.tf deleted file mode 100644 index a3319169a..000000000 --- a/outputs.tf +++ /dev/null @@ -1,4 +0,0 @@ -output "api_address" { - value = aws_api_gateway_stage.default_audit_stream.invoke_url - description = "Invoke URL for the API" -} From 4c1a8a159366b3074804fddc325899e5e8683803 Mon Sep 17 00:00:00 2001 From: Jon M Date: Thu, 21 Dec 2023 09:34:05 +0000 Subject: [PATCH 4/9] tidy up and documentation --- README.md | 2 ++ hooks/terraform_docs.sh | 23 ++++++++--------------- 2 files changed, 10 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index d7a240246..888de4c0e 100644 --- a/README.md +++ b/README.md @@ -486,6 +486,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files * create a documentation file * extend existing documentation file by appending markers to the end of the file (see item 1 above) * use different filename for the documentation (default is `README.md`) + * use the same insertion markers as `terraform-docs`, i.e. `...` ```yaml - id: terraform_docs @@ -493,6 +494,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files - --hook-config=--path-to-file=README.md # Valid UNIX path. I.e. ../TFDOC.md or docs/README.md etc. - --hook-config=--add-to-existing-file=true # Boolean. true or false - --hook-config=--create-file-if-not-exist=true # Boolean. true or false + - --hook-config=--use-standard-markers=true # Boolean. Defaults to false. Set to true for compatibility with terraform-docs ``` 4. You can provide [any configuration available in `terraform-docs`](https://terraform-docs.io/user-guide/configuration/) as an argument to `terraform_doc` hook, for example: diff --git a/hooks/terraform_docs.sh b/hooks/terraform_docs.sh index 42b0ceb15..6f3559d5b 100755 --- a/hooks/terraform_docs.sh +++ b/hooks/terraform_docs.sh @@ -8,7 +8,7 @@ readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)" . "$SCRIPT_DIR/_common.sh" # set up default insertion markers. These will be changed to the markers used by -# terraform-docs if the hook config contains `--use_standard_markers=true` +# terraform-docs if the hook config contains `--use-standard-markers=true` insertion_marker_begin="" insertion_marker_end="" @@ -42,22 +42,18 @@ function terraform_docs_ { # Get hook settings IFS=";" read -r -a configs <<< "$hook_config" - # Variable to store the standard markers argument use_standard_markers=false - # Iterate through the array for arg in "${configs[@]}"; do # remove leading whitespace characters arg="${arg#"${arg%%[![:space:]]*}"}" - # Check if the argument starts with 'use_standard_markers=' - if [[ $arg == '--use_standard_markers='* ]]; then + # Check if the argument starts with 'use-standard-markers=' + if [[ $arg == '--use-standard-markers='* ]]; then # Extract the value after '=' and store it in the use_standard_markers variable use_standard_markers="${arg#*=}" - # Remove the argument from the array + # Remove the argument from the array and break out of the loop configs=("${configs[@]/$arg/}") - - # Break out of the loop since argument has been found break fi done @@ -66,6 +62,7 @@ function terraform_docs_ { echo "Remaining hook config: ${configs[@]}" if [ "$use_standard_markers" = true ] ; then + # update the insertion markers to those used by terraform-docs insertion_marker_begin="" insertion_marker_end="" fi @@ -212,8 +209,7 @@ function terraform_docs { mkdir -p "$dir" - echo "FIRST USE: $insertion_marker_begin (NO README)" - + # Use of insertion markers, where there is no existing README file { echo -e "# ${PWD##*/}\n" echo $insertion_marker_begin @@ -232,8 +228,7 @@ function terraform_docs { HAVE_MARKER=$(grep -o "$insertion_marker_begin" "$text_file" || exit 0) if [ ! "$HAVE_MARKER" ]; then - echo "SECOND USE: $insertion_marker_begin (addToExisting with no marker in file)" - + # Use of insertion markers, where addToExisting=true, with no markers in the existing file echo $insertion_marker_begin >> "$text_file" echo $insertion_marker_end >> "$text_file" fi @@ -256,12 +251,10 @@ function terraform_docs { rm -f "$tmp_file_docs_tf" fi - echo "THIRD USE: $insertion_marker_begin (UPDATE DOC)" - + # Use of insertion markers to insert the terraform-docs output between the markers # Replace content between markers with the placeholder - https://stackoverflow.com/questions/1212799/how-do-i-extract-lines-between-two-line-delimiters-in-perl#1212834 perl_expression="if (/$insertion_marker_begin/../$insertion_marker_end/) { print \$_ if /$insertion_marker_begin/; print \"I_WANT_TO_BE_REPLACED\\n\$_\" if /$insertion_marker_end/;} else { print \$_ }" perl -i -ne "$perl_expression" "$text_file" - echo "$perl_expression" # Replace placeholder with the content of the file perl -i -e 'open(F, "'"$tmp_file"'"); $f = join "", ; while(<>){if (/I_WANT_TO_BE_REPLACED/) {print $f} else {print $_};}' "$text_file" From 2080f48ee969d43046e09efb0a79f2da96060852 Mon Sep 17 00:00:00 2001 From: Jon McEwen Date: Thu, 21 Dec 2023 12:21:37 +0000 Subject: [PATCH 5/9] Fix comment Co-authored-by: George L. Yermulnik --- hooks/terraform_docs.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hooks/terraform_docs.sh b/hooks/terraform_docs.sh index 6f3559d5b..c514a3912 100755 --- a/hooks/terraform_docs.sh +++ b/hooks/terraform_docs.sh @@ -47,7 +47,7 @@ function terraform_docs_ { for arg in "${configs[@]}"; do # remove leading whitespace characters arg="${arg#"${arg%%[![:space:]]*}"}" - # Check if the argument starts with 'use-standard-markers=' + # Check if the argument starts with '--use-standard-markers=' if [[ $arg == '--use-standard-markers='* ]]; then # Extract the value after '=' and store it in the use_standard_markers variable use_standard_markers="${arg#*=}" From 634235558b40f0edcb96f56658f18b514b17a1c6 Mon Sep 17 00:00:00 2001 From: Jon McEwen Date: Thu, 21 Dec 2023 14:08:41 +0000 Subject: [PATCH 6/9] refactor after review --- hooks/terraform_docs.sh | 47 ++++++++++++++++------------------------- 1 file changed, 18 insertions(+), 29 deletions(-) diff --git a/hooks/terraform_docs.sh b/hooks/terraform_docs.sh index c514a3912..c597730b0 100755 --- a/hooks/terraform_docs.sh +++ b/hooks/terraform_docs.sh @@ -12,6 +12,10 @@ readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)" insertion_marker_begin="" insertion_marker_end="" +# these are the standard insertion markers used by terraform-docs +readonly standard_insertion_marker_begin="" +readonly standard_insertion_marker_end="" + function main { common::initialize "$SCRIPT_DIR" common::parse_cmdline "$@" @@ -42,31 +46,6 @@ function terraform_docs_ { # Get hook settings IFS=";" read -r -a configs <<< "$hook_config" - use_standard_markers=false - - for arg in "${configs[@]}"; do - # remove leading whitespace characters - arg="${arg#"${arg%%[![:space:]]*}"}" - # Check if the argument starts with '--use-standard-markers=' - if [[ $arg == '--use-standard-markers='* ]]; then - # Extract the value after '=' and store it in the use_standard_markers variable - use_standard_markers="${arg#*=}" - - # Remove the argument from the array and break out of the loop - configs=("${configs[@]/$arg/}") - break - fi - done - - echo "Use standard markers: $use_standard_markers" - echo "Remaining hook config: ${configs[@]}" - - if [ "$use_standard_markers" = true ] ; then - # update the insertion markers to those used by terraform-docs - insertion_marker_begin="" - insertion_marker_end="" - fi - local hack_terraform_docs hack_terraform_docs=$(terraform version | sed -n 1p | grep -c 0.12) || true @@ -141,6 +120,7 @@ function terraform_docs { local text_file="README.md" local add_to_existing=false local create_if_not_exist=false + local use_standard_markers=false read -r -a configs <<< "$hook_config" @@ -160,9 +140,18 @@ function terraform_docs { --create-file-if-not-exist) create_if_not_exist=$value ;; + --use-standard-markers) + use_standard_markers=$value + ;; esac done + if [ "$use_standard_markers" = true ]; then + # update the insertion markers to those used by terraform-docs + insertion_marker_begin="$standard_insertion_marker_begin" + insertion_marker_end="$standard_insertion_marker_end" + fi + # Override formatter if no config file set if [[ "$args" != *"--config"* ]]; then local tf_docs_formatter="md" @@ -212,8 +201,8 @@ function terraform_docs { # Use of insertion markers, where there is no existing README file { echo -e "# ${PWD##*/}\n" - echo $insertion_marker_begin - echo $insertion_marker_end + echo "$insertion_marker_begin" + echo "$insertion_marker_end" } >> "$text_file" fi @@ -229,8 +218,8 @@ function terraform_docs { if [ ! "$HAVE_MARKER" ]; then # Use of insertion markers, where addToExisting=true, with no markers in the existing file - echo $insertion_marker_begin >> "$text_file" - echo $insertion_marker_end >> "$text_file" + echo "$insertion_marker_begin" >> "$text_file" + echo "$insertion_marker_end" >> "$text_file" fi fi From 37a89491ce1540c802da843db3ae190c005f474d Mon Sep 17 00:00:00 2001 From: Maksym Vlasov Date: Thu, 21 Dec 2023 21:49:27 +0200 Subject: [PATCH 7/9] Specify how to migrate on new marker version --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 888de4c0e..9cfde7d0f 100644 --- a/README.md +++ b/README.md @@ -486,7 +486,13 @@ Unlike most other hooks, this hook triggers once if there are any changed files * create a documentation file * extend existing documentation file by appending markers to the end of the file (see item 1 above) * use different filename for the documentation (default is `README.md`) - * use the same insertion markers as `terraform-docs`, i.e. `...` + * use the same insertion markers as `terraform-docs` by default. It will be default in `v2.0`. + To migrate to `terraform-docs` insertion markers, run in repo root: + + ```bash + grep -rl 'BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/BEGIN_TF_DOCS/g' + grep -rl 'END OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/END OF PRE-COMMIT-TERRAFORM DOCS HOOK/END_TF_DOCS/g' + ``` ```yaml - id: terraform_docs @@ -494,7 +500,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files - --hook-config=--path-to-file=README.md # Valid UNIX path. I.e. ../TFDOC.md or docs/README.md etc. - --hook-config=--add-to-existing-file=true # Boolean. true or false - --hook-config=--create-file-if-not-exist=true # Boolean. true or false - - --hook-config=--use-standard-markers=true # Boolean. Defaults to false. Set to true for compatibility with terraform-docs + - --hook-config=--use-standard-markers=true # Boolean. Defaults in v1.x to false. Set to true for compatibility with terraform-docs ``` 4. You can provide [any configuration available in `terraform-docs`](https://terraform-docs.io/user-guide/configuration/) as an argument to `terraform_doc` hook, for example: From 50419b6af303b60015cac203d7c7f7608f0ec48a Mon Sep 17 00:00:00 2001 From: Maksym Vlasov Date: Thu, 21 Dec 2023 21:50:37 +0200 Subject: [PATCH 8/9] Apply suggestions from code review --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9cfde7d0f..5629e732b 100644 --- a/README.md +++ b/README.md @@ -489,10 +489,10 @@ Unlike most other hooks, this hook triggers once if there are any changed files * use the same insertion markers as `terraform-docs` by default. It will be default in `v2.0`. To migrate to `terraform-docs` insertion markers, run in repo root: - ```bash - grep -rl 'BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/BEGIN_TF_DOCS/g' - grep -rl 'END OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/END OF PRE-COMMIT-TERRAFORM DOCS HOOK/END_TF_DOCS/g' - ``` + ```bash + grep -rl 'BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/BEGIN_TF_DOCS/g' + grep -rl 'END OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/END OF PRE-COMMIT-TERRAFORM DOCS HOOK/END_TF_DOCS/g' + ``` ```yaml - id: terraform_docs From 661e63a2ebb46a913f3e4bce9fe875c0f86d5ea5 Mon Sep 17 00:00:00 2001 From: Maksym Vlasov Date: Thu, 21 Dec 2023 21:57:37 +0200 Subject: [PATCH 9/9] Apply suggestions from code review --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5629e732b..b4eef7d66 100644 --- a/README.md +++ b/README.md @@ -488,7 +488,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files * use different filename for the documentation (default is `README.md`) * use the same insertion markers as `terraform-docs` by default. It will be default in `v2.0`. To migrate to `terraform-docs` insertion markers, run in repo root: - + ```bash grep -rl 'BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/BEGIN_TF_DOCS/g' grep -rl 'END OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/END OF PRE-COMMIT-TERRAFORM DOCS HOOK/END_TF_DOCS/g'