feat(terraform_docs): Start seamless migration to terraform-docs markers (antonbabenko#701)

---------

Co-authored-by: George L. Yermulnik <[email protected]>

Author: MaxymVlasov

README.md

@@ -568,9 +568,9 @@ Unlike most other hooks, this hook triggers once if there are any changed files
 1. `terraform_docs` and `terraform_docs_without_aggregate_type_defaults` will insert/update documentation generated by [terraform-docs](https://github.com/terraform-docs/terraform-docs) framed by markers:
 
     ```txt
-    <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+    <!-- BEGIN_TF_DOCS -->
 
-    <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+    <!-- END_TF_DOCS -->
     ```
 
     if they are present in `README.md`.
@@ -581,8 +581,8 @@ 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:
+    * use the same insertion markers as `terraform-docs`. It's default starting from `v1.93`.  
+      To migrate everything 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'
@@ -595,7 +595,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 in v1.x to false. Set to true for compatibility with terraform-docs
+        - --hook-config=--use-standard-markers=true     # Boolean. Defaults to true (v1.93+), false (<v1.93). 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,14 +7,12 @@ readonly SCRIPT_DIR
 # 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 -->"
+insertion_marker_begin="<!-- BEGIN_TF_DOCS -->"
+insertion_marker_end="<!-- END_TF_DOCS -->"
 
-# 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 -->"
+# Old markers used by the hook before the introduction of the terraform-docs markers
+readonly old_insertion_marker_begin="<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
+readonly old_insertion_marker_end="<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
 
 function main {
   common::initialize "$SCRIPT_DIR"
@@ -29,6 +27,23 @@ function main {
   terraform_docs_ "${HOOK_CONFIG[*]}" "${ARGS[*]}" "${FILES[@]}"
 }
 
+#######################################################################
+# Function to replace old markers with new markers affected files
+# Globals:
+#   insertion_marker_begin - Standard insertion marker at beginning
+#   insertion_marker_end - Standard insertion marker at the end
+#   old_insertion_marker_begin - Old insertion marker at beginning
+#   old_insertion_marker_end - Old insertion marker at the end
+# Arguments:
+#   file (string) filename to check
+#######################################################################
+function replace_old_markers {
+  local -r file=$1
+
+  sed -i "s/^${old_insertion_marker_begin}$/${insertion_marker_begin}/" "$file"
+  sed -i "s/^${old_insertion_marker_end}$/${insertion_marker_end}/" "$file"
+}
+
 #######################################################################
 # Function which prepares hacks for old versions of `terraform` and
 # `terraform-docs` that them call `terraform_docs`
@@ -124,7 +139,7 @@ function terraform_docs {
   local use_path_to_file=false
   local add_to_existing=false
   local create_if_not_exist=false
-  local use_standard_markers=false
+  local use_standard_markers=true
 
   read -r -a configs <<< "$hook_config"
 
@@ -147,14 +162,16 @@ function terraform_docs {
         ;;
       --use-standard-markers)
         use_standard_markers=$value
+        common::colorify "yellow" "WARNING: --use-standard-markers is deprecated and will be removed in the future."
+        common::colorify "yellow" "         All needed changes already done by the hook, feel free to remove --use-standard-markers setting from your pre-commit config"
         ;;
     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"
+  if [[ $use_standard_markers == false ]]; then
+    # update the insertion markers to those used by pre-commit-terraform before v1.93
+    insertion_marker_begin="$old_insertion_marker_begin"
+    insertion_marker_end="$old_insertion_marker_end"
   fi
 
   # Override formatter if no config file set
@@ -232,6 +249,8 @@ function terraform_docs {
     # If file still not exist - skip dir
     [[ ! -f "$text_file" ]] && popd > /dev/null && continue
 
+    replace_old_markers "$text_file"
+
     #
     # If `--add-to-existing-file=true` set, check is in file exist "hook markers",
     # and if not - append "hook markers" to the end of file.