feat(terraform_docs): Add terraform-docs default markers support and describe how to migrate to them (antonbabenko#609)

---------

Co-authored-by: Jon M <[email protected]>
Co-authored-by: George L. Yermulnik <[email protected]>
Co-authored-by: Maksym Vlasov <[email protected]>

Author: 4 people

README.md

@@ -486,13 +486,21 @@ 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` 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
       args:
         - --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 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:

hooks/terraform_docs.sh

@@ -7,6 +7,15 @@ 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="<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
+insertion_marker_end="<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
+
+# these are the standard insertion markers used by terraform-docs
+readonly standard_insertion_marker_begin="<!-- BEGIN_TF_DOCS -->"
+readonly standard_insertion_marker_end="<!-- END_TF_DOCS -->"
+
 function main {
   common::initialize "$SCRIPT_DIR"
   common::parse_cmdline "$@"
@@ -111,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"
 
@@ -130,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"
@@ -178,10 +197,12 @@ function terraform_docs {
       dir="$(dirname "$text_file")"
 
       mkdir -p "$dir"
+
+      # Use of insertion markers, where there is no existing README file
       {
         echo -e "# ${PWD##*/}\n"
-        echo "<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
-        echo "<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
+        echo "$insertion_marker_begin"
+        echo "$insertion_marker_end"
       } >> "$text_file"
     fi
 
@@ -193,11 +214,12 @@ function terraform_docs {
     # and if not - append "hook markers" to the end of file.
     #
     if $add_to_existing; then
-      HAVE_MARKER=$(grep -o '<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->' "$text_file" || exit 0)
+      HAVE_MARKER=$(grep -o "$insertion_marker_begin" "$text_file" || exit 0)
 
       if [ ! "$HAVE_MARKER" ]; then
-        echo "<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->" >> "$text_file"
-        echo "<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->" >> "$text_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
     fi
 
@@ -218,8 +240,10 @@ function terraform_docs {
       rm -f "$tmp_file_docs_tf"
     fi
 
+    # 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 -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"
 
     # Replace placeholder with the content of the file
     perl -i -e 'open(F, "'"$tmp_file"'"); $f = join "", <F>; while(<>){if (/I_WANT_TO_BE_REPLACED/) {print $f} else {print $_};}' "$text_file"