Add new hook for running terraform-docs which will replace content of README.md (using Python)

.pre-commit-hooks.yaml

@@ -23,6 +23,14 @@
   files: (\.tf)$
   exclude: \.terraform\/.*$
 
+- id: terraform_docs_replace
+  name: Terraform docs (overwrite README.md)
+  language: python
+  entry: terraform_docs_replace
+  files: (\.tf)$
+  exclude: \.terraform\/.*$
+  description: Overwrite content of README.md with terraform-docs
+
 - id: terraform_validate_no_variables
   name: Terraform validate without variables
   description: Validates all Terraform configuration files without checking whether all required variables were set (basic check).

README.md

@@ -52,6 +52,7 @@ There are several [pre-commit](http://pre-commit.com/) hooks to keep Terraform c
 * `terraform_validate_with_variables` - Validates all Terraform configuration files and checks whether all required variables were specified.
 * `terraform_docs` - Inserts input and output documentation into `README.md`. Recommended.
 * `terraform_docs_without_aggregate_type_defaults` - Inserts input and output documentation into `README.md` without aggregate type defaults.
+* `terraform_docs_replace` - Runs `terraform-docs` and pipes the output directly to README.md
 
 Check the [source file](https://github.com/antonbabenko/pre-commit-terraform/blob/master/.pre-commit-hooks.yaml) to know arguments used for each hook.
 
@@ -61,6 +62,15 @@ Check the [source file](https://github.com/antonbabenko/pre-commit-terraform/blo
 
 1. `terraform_docs` and `terraform_docs_without_aggregate_type_defaults` will insert/update documentation generated by [terraform-docs](https://github.com/segmentio/terraform-docs) between markers - `<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->` and `<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->` if they are present in `README.md`. Make sure that `terraform-docs` is installed.
 
+1. `terraform_docs_replace` replaces the entire README.md rather than doing string replacement between markers. Put your additional documentation at the top of your `main.tf` for it to be pulled in. The optional `--dest` argument lets your change the name of the file that gets created/modified
+
+    1. Example:
+    ```yaml
+    hooks:
+      - id: terraform_docs_replace
+        args: ['--with-aggregate-type-defaults', '--sort-inputs-by-required', '--dest=TEST.md']
+    ```
+
 1. It is possible to pass additional arguments to shell scripts when using `terraform_docs` and `terraform_docs_without_aggregate_type_defaults`. Send pull-request with the new hook if there is something missing.
 
 Enjoy the clean and documented code!

pre_commit_hooks/terraform_docs_replace.py

@@ -0,0 +1,55 @@
+import argparse
+import os
+import subprocess
+import sys
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="""Run terraform-docs on a set of files. Follows the standard convention of
+                       pulling the documentation from main.tf in order to replace the entire
+                       README.md file each time."""
+    )
+    parser.add_argument(
+        '--dest', dest='dest', default='README.md',
+    )
+    parser.add_argument(
+        '--sort-inputs-by-required', dest='sort', action='store_true',
+    )
+    parser.add_argument(
+        '--with-aggregate-type-defaults', dest='aggregate', action='store_true',
+    )
+    parser.add_argument('filenames', nargs='*', help='Filenames to check.')
+    args = parser.parse_args(argv)
+
+    dirs = []
+    for filename in args.filenames:
+        if (os.path.realpath(filename) not in dirs and \
+                len(os.path.realpath(filename).strip()) > 0 and \
+                (filename.endswith(".tf") or filename.endswith(".tfvars"))):
+            dirs.append(os.path.dirname(filename))
+
+    retval = 0
+
+    for dir in dirs:
+        try:
+            procArgs = []
+            procArgs.append('terraform-docs')
+            if args.sort:
+                procArgs.append('--sort-inputs-by-required')
+            if args.aggregate:
+                procArgs.append('--with-aggregate-type-defaults')
+            procArgs.append('md')
+            procArgs.append(dir)
+            procArgs.append("| sed -e '$ d' -e 'N;/^\\n$/D;P;D'")
+            procArgs.append('>')
+            procArgs.append("./{dir}/{dest}".format(dir=dir,dest=args.dest))
+            subprocess.check_call(" ".join(procArgs), shell=True)
+        except subprocess.CalledProcessError as e:
+            print(e)
+            retval = 1
+    return retval
+
+
+if __name__ == '__main__':
+    sys.exit(main())

setup.py

@@ -0,0 +1,34 @@
+from setuptools import find_packages
+from setuptools import setup
+
+
+setup(
+    name='pre-commit-terraform',
+    description='Pre-commit hooks for terraform_docs_replace',
+    url='https://github.com/antonbabenko/pre-commit-terraform',
+    version_format='{tag}+{gitsha}',
+
+    author='Andrew Roth',
+    author_email='[email protected]',
+
+    classifiers=[
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 2',
+        'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python :: Implementation :: CPython',
+        'Programming Language :: Python :: Implementation :: PyPy',
+    ],
+
+    packages=find_packages(exclude=('tests*', 'testing*')),
+    install_requires=[
+        'setuptools-git-version',
+    ],
+    entry_points={
+        'console_scripts': [
+            'terraform_docs_replace = pre_commit_hooks.terraform_docs_replace:main',
+        ],
+    },
+)