feat: ignore outputs, providers, resources with comments

Prepend any type of resource, including `resource`, `data`, `module`,
`variable`, and `output` with a comment including "terraform-docs-ignore"
to exclude it from the generated output.

Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>

docs/how-to/generate-terraform-tfvars.md

@@ -4,7 +4,7 @@ description: "How to generate terraform.tfvars file with terraform-docs"
 menu:
   docs:
     parent: "how-to"
-weight: 207
+weight: 208
 toc: false
 ---
 

docs/how-to/github-action.md

@@ -4,7 +4,7 @@ description: "How to use terraform-docs with GitHub Actions"
 menu:
   docs:
     parent: "how-to"
-weight: 208
+weight: 209
 toc: false
 ---
 

docs/how-to/ignore-resources.md

@@ -0,0 +1,74 @@
+---
+title: "Ignore Resources to be Generated"
+description: "How to ignore resources from generated output"
+menu:
+  docs:
+    parent: "how-to"
+weight: 204
+toc: false
+---
+
+Since `v0.18.0`
+
+Any type of resources can be ignored from the generated output by prepending them
+with a comment `terraform-docs-ignore`. Supported type of Terraform resources to
+get ignored are:
+
+- `resource`
+- `data`
+- `module`
+- `variable`
+- `output`
+
+{{< alert type="info" >}}
+If a `resource` or `data` is ignored, their corresponding discovered provider
+will also get ignored from "Providers" section.
+{{< /alert>}}
+
+Take the following example:
+
+```hcl
+##################################################################
+# All of the following will be ignored from the generated output #
+##################################################################
+
+# terraform-docs-ignore
+resource "foo_resource" "foo" {}
+
+# This resource is going to get ignored from generated
+# output by using the following known comment.
+#
+# terraform-docs-ignore
+#
+# The ignore keyword also doesn't have to be the first,
+# last, or the only thing in a leading comment
+resource "bar_resource" "bar" {}
+
+# terraform-docs-ignore
+data "foo_data_resource" "foo" {}
+
+# terraform-docs-ignore
+data "bar_data_resource" "bar" {}
+
+// terraform-docs-ignore
+module "foo" {
+  source  = "foo"
+  version = "x.x.x"
+}
+
+# terraform-docs-ignore
+variable "foo" {
+  default = "foo"
+}
+
+// terraform-docs-ignore
+output "foo" {
+  value = "foo"
+}
+```
+
+{{< alert type="info" >}}
+The ignore keyword (i.e. `terraform-docs-ignore`) doesn't have to be the first,
+last, or only thing in a leading comment. As long as the keyword is present in
+a comment, the following resource will get ignored.
+{{< /alert>}}

docs/how-to/include-examples.md

@@ -4,7 +4,7 @@ description: "How to include example in terraform-docs generated output"
 menu:
   docs:
     parent: "how-to"
-weight: 205
+weight: 206
 toc: false
 ---
 

docs/how-to/insert-output-to-file.md

@@ -4,7 +4,7 @@ description: "How to insert generated terraform-docs output to file"
 menu:
   docs:
     parent: "how-to"
-weight: 204
+weight: 205
 toc: false
 ---
 

docs/how-to/pre-commit-hooks.md

@@ -4,7 +4,7 @@ description: "How to use pre-commit hooks with terraform-docs"
 menu:
   docs:
     parent: "how-to"
-weight: 209
+weight: 210
 toc: false
 ---
 

docs/how-to/recursive-submodules.md

@@ -4,7 +4,7 @@ description: "How to generate submodules documentation recursively with terrafor
 menu:
   docs:
     parent: "how-to"
-weight: 206
+weight: 207
 toc: false
 ---
 

examples/main.tf

@@ -63,8 +63,20 @@ data "aws_caller_identity" "ident" {
   provider = "aws.ident"
 }
 
+# terraform-docs-ignore
+data "aws_caller_identity" "ignored" {
+  provider = "aws"
+}
+
 resource "null_resource" "foo" {}
 
+# This resource is going to get ignored from generated
+# output by using the following known comment.
+# terraform-docs-ignore
+# And the ignore keyword also doesn't have to be the first,
+# last, or only thing in a leading comment
+resource "null_resource" "ignored" {}
+
 module "bar" {
   source  = "baz"
   version = "4.5.6"
@@ -84,3 +96,9 @@ module "baz" {
 module "foobar" {
   source = "git@github.com:module/path?ref=v7.8.9"
 }
+
+// terraform-docs-ignore
+module "ignored" {
+  source  = "foobaz"
+  version = "7.8.9"
+}

examples/outputs.tf

@@ -17,3 +17,8 @@ output "output-0.12" {
   value       = join(",", var.list-3)
   description = "terraform 0.12 only"
 }
+
+// terraform-docs-ignore
+output "ignored" {
+  value = "ignored"
+}

examples/variables.tf

@@ -14,6 +14,11 @@ variable "bool-1" {
   default = true
 }
 
+# terraform-docs-ignore
+variable "ignored" {
+  default = ""
+}
+
 variable "string-3" {
   default = ""
 }

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/spf13/viper v1.18.2
 	github.com/stretchr/testify v1.9.0
 	github.com/terraform-docs/terraform-config-inspect v0.0.0-20210728164355-9c1f178932fa
+	golang.org/x/exp v0.0.0-20240525044651-4c93da0ed11d
 	gopkg.in/yaml.v3 v3.0.1
 	honnef.co/go/tools v0.3.2
 	mvdan.cc/xurls/v2 v2.5.0
@@ -58,7 +59,6 @@ require (
 	github.com/zclconf/go-cty v1.14.4 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/crypto v0.23.0 // indirect
-	golang.org/x/exp v0.0.0-20240525044651-4c93da0ed11d // indirect
 	golang.org/x/exp/typeparams v0.0.0-20220722155223-a9213eeb770e // indirect
 	golang.org/x/mod v0.17.0 // indirect
 	golang.org/x/net v0.25.0 // indirect

terraform/load.go

@@ -189,7 +189,7 @@ func loadInputs(tfmodule *tfconfig.Module, config *print.Config) ([]*Input, []*I
 	for _, input := range tfmodule.Variables {
 		comments := loadComments(input.Pos.Filename, input.Pos.Line)
 
-		// Skip over inputs that are marked as being ignored
+		// skip over inputs that are marked as being ignored
 		if strings.Contains(comments, "terraform-docs-ignore") {
 			continue
 		}
@@ -252,13 +252,20 @@ func loadModulecalls(tfmodule *tfconfig.Module, config *print.Config) []*ModuleC
 	var source, version string
 
 	for _, m := range tfmodule.ModuleCalls {
-		source, version = formatSource(m.Source, m.Version)
+		comments := loadComments(m.Pos.Filename, m.Pos.Line)
+
+		// skip over modules that are marked as being ignored
+		if strings.Contains(comments, "terraform-docs-ignore") {
+			continue
+		}
 
 		description := ""
 		if config.Settings.ReadComments {
-			description = loadComments(m.Pos.Filename, m.Pos.Line)
+			description = comments
 		}
 
+		source, version = formatSource(m.Source, m.Version)
+
 		modules = append(modules, &ModuleCall{
 			Name:        m.Name,
 			Source:      source,
@@ -284,10 +291,17 @@ func loadOutputs(tfmodule *tfconfig.Module, config *print.Config) ([]*Output, er
 		}
 	}
 	for _, o := range tfmodule.Outputs {
+		comments := loadComments(o.Pos.Filename, o.Pos.Line)
+
+		// skip over outputs that are marked as being ignored
+		if strings.Contains(comments, "terraform-docs-ignore") {
+			continue
+		}
+
 		// convert CRLF to LF early on (https://github.com/terraform-docs/terraform-docs/issues/584)
 		description := strings.ReplaceAll(o.Description, "\r\n", "\n")
 		if description == "" && config.Settings.ReadComments {
-			description = loadComments(o.Pos.Filename, o.Pos.Line)
+			description = comments
 		}
 
 		output := &Output{
@@ -337,7 +351,11 @@ func loadOutputValues(config *print.Config) (map[string]*output, error) {
 	return terraformOutputs, err
 }
 
-func loadProviders(tfmodule *tfconfig.Module, config *print.Config) []*Provider {
+func loadProviders(tfmodule *tfconfig.Module, config *print.Config) []*Provider { //nolint:gocyclo
+	// NOTE(khos2ow): this function is over our cyclomatic complexity goal.
+	// Be wary when adding branches, and look for functionality that could
+	// be reasonably moved into an injected dependency.
+
 	type provider struct {
 		Name        string   `hcl:"name,label"`
 		Version     string   `hcl:"version"`
@@ -367,6 +385,13 @@ func loadProviders(tfmodule *tfconfig.Module, config *print.Config) []*Provider
 
 	for _, resource := range resources {
 		for _, r := range resource {
+			comments := loadComments(r.Pos.Filename, r.Pos.Line)
+
+			// skip over resources that are marked as being ignored
+			if strings.Contains(comments, "terraform-docs-ignore") {
+				continue
+			}
+
 			var version = ""
 			if l, ok := lock[r.Provider.Name]; ok {
 				version = l.Version
@@ -375,6 +400,10 @@ func loadProviders(tfmodule *tfconfig.Module, config *print.Config) []*Provider
 			}
 
 			key := fmt.Sprintf("%s.%s", r.Provider.Name, r.Provider.Alias)
+			if _, ok := discovered[key]; ok {
+				continue
+			}
+
 			discovered[key] = &Provider{
 				Name:    r.Provider.Name,
 				Alias:   types.String(r.Provider.Alias),
@@ -391,6 +420,7 @@ func loadProviders(tfmodule *tfconfig.Module, config *print.Config) []*Provider
 	for _, provider := range discovered {
 		providers = append(providers, provider)
 	}
+
 	return providers
 }
 
@@ -427,6 +457,13 @@ func loadResources(tfmodule *tfconfig.Module, config *print.Config) []*Resource
 
 	for _, resource := range allResources {
 		for _, r := range resource {
+			comments := loadComments(r.Pos.Filename, r.Pos.Line)
+
+			// skip over resources that are marked as being ignored
+			if strings.Contains(comments, "terraform-docs-ignore") {
+				continue
+			}
+
 			var version string
 			if rv, ok := tfmodule.RequiredProviders[r.Provider.Name]; ok {
 				version = resourceVersion(rv.VersionConstraints)
@@ -444,7 +481,7 @@ func loadResources(tfmodule *tfconfig.Module, config *print.Config) []*Resource
 
 			description := ""
 			if config.Settings.ReadComments {
-				description = loadComments(r.Pos.Filename, r.Pos.Line)
+				description = comments
 			}
 
 			discovered[key] = &Resource{