Add support for generating docs for list-resources

.changes/unreleased/FEATURES-20251001-095120.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'generate/migrate/validate: Add support for list resources'
+time: 2025-10-01T09:51:20.683445+02:00
+custom:
+    Issue: "528"

README.md

@@ -118,6 +118,7 @@ When you run `tfplugindocs`, by default from the root directory of a provider co
 * Generate function template files, if missing (Requires Terraform v1.8.0+)
 * Generate ephemeral resource template files, if missing (Requires Terraform v1.10.0+)
 * Generate action template files, if missing (Requires Terraform v1.14.0+)
+* Generate list resource templeate files, if missing (Requires Terraform v1.14.0+)
 * Copy all non-template files to the output website directory
 
 > [!NOTE]
@@ -204,20 +205,22 @@ For templates:
 
 > **NOTE:** In the following conventional paths for templates, `<data source name>`, `<resource name>`, and `<function name>` do not include the provider prefix.
 
-| Path                                                               | Description                                   |
-|--------------------------------------------------------------------|-----------------------------------------------|
-| `templates/`                                                       | Root of templated docs                        |
-| `templates/index.md[.tmpl]`                                        | Docs index page (or template)                 |
-| `templates/actions.md[.tmpl]`                                      | Generic action page (or template)             |
-| `templates/actions/<action type name>.md[.tmpl]`                   | Action page (or template)                     |
-| `templates/data-sources.md[.tmpl]`                                 | Generic data source page (or template)        |
-| `templates/data-sources/<data source name>.md[.tmpl]`              | Data source page (or template)                |
-| `templates/ephemeral-resources.md[.tmpl]`                          | Generic ephemeral resource page (or template) |
-| `templates/ephemeral-resources/<ephemeral resource name>.md[.tmpl]`| Ephemeral resource page (or template)         |
-| `templates/functions.md[.tmpl]`                                    | Generic function page (or template)           |
-| `templates/functions/<function name>.md[.tmpl]`                    | Function page (or template)                   |
-| `templates/resources.md[.tmpl]`                                    | Generic resource page (or template)           |
-| `templates/resources/<resource name>.md[.tmpl]`                    | Resource page (or template)                   |
+| Path                                                                | Description                                   |
+|---------------------------------------------------------------------|-----------------------------------------------|
+| `templates/`                                                        | Root of templated docs                        |
+| `templates/index.md[.tmpl]`                                         | Docs index page (or template)                 |
+| `templates/actions.md[.tmpl]`                                       | Generic action page (or template)             |
+| `templates/actions/<action type name>.md[.tmpl]`                    | Action page (or template)                     |
+| `templates/data-sources.md[.tmpl]`                                  | Generic data source page (or template)        |
+| `templates/data-sources/<data source name>.md[.tmpl]`               | Data source page (or template)                |
+| `templates/ephemeral-resources.md[.tmpl]`                           | Generic ephemeral resource page (or template) |
+| `templates/ephemeral-resources/<ephemeral resource name>.md[.tmpl]` | Ephemeral resource page (or template)         |
+| `templates/functions.md[.tmpl]`                                     | Generic function page (or template)           |
+| `templates/functions/<function name>.md[.tmpl]`                     | Function page (or template)                   |
+| `templates/list-resources.md[.tmpl]`                                | Generic list resource page (or template)      |
+| `templates/list-resources/<list resource name>.md[.tmpl]`           | List resource page (or template)              |
+| `templates/resources.md[.tmpl]`                                     | Generic resource page (or template)           |
+| `templates/resources/<resource name>.md[.tmpl]`                     | Resource page (or template)                   |
 
 Note: the `.tmpl` extension is necessary, for the file to be correctly handled as a template.
 
@@ -234,6 +237,7 @@ For examples:
 | `examples/data-sources/<data source name>/data-source<*>.tf`                 | Data source example config(s)              |
 | `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource<*>.tf` | Ephemeral resource example config(s)       |
 | `examples/functions/<function name>/function<*>.tf`                          | Function example config(s)                 |
+| `examples/list-resources/<list resource>/list-resource<*>.tfquery.hcl`       | List resource example config(s)            |
 | `examples/resources/<resource name>/resource<*>.tf`                          | Resource example config(s)                 |
 | `examples/resources/<resource name>/import.sh`                               | Resource example import command            |
 | `examples/resources/<resource name>/import-by-string-id.tf`                  | Resource example import by id config       |
@@ -257,6 +261,7 @@ Legacy website directory structure:
 | `website/docs/d/<data source name>.html.markdown`                          | Data source page            |
 | `website/docs/ephemeral-resources/<ephemeral resource name>.html.markdown` | Ephemeral resource page     |
 | `website/docs/functons/<function name>.html.markdown`                      | Functions page              |
+| `website/docs/list-resources/<list resource name>.html.markdown`           | List resource page          |
 | `website/docs/r/<resource name>.html.markdown`                             | Resource page               |
 
 Docs website directory structure:
@@ -270,6 +275,7 @@ Docs website directory structure:
 | `docs/data-sources/<data source name>.html.markdown`               | Data source page            |
 | `docs/ephemeral-resources/<ephemeral resource name>.html.markdown` | Ephemeral resource page     |
 | `docs/functions/<function name>.html.markdown`                     | Function page               |
+| `docs/list-resources/<list resource name>.html.markdown`           | List resource page          |
 | `docs/resources/<resource name>.html.markdown`                     | Resource page               |
 
 Files named `index` (before the first `.`) in the website docs root directory and files in the `website/docs/d/`, `website/docs/r/`, `docs/data-sources/`,
@@ -357,6 +363,22 @@ using the following data fields and functions:
 | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
 | `.SchemaMarkdown`       | string | a Markdown formatted Action Schema definition                                             |
 
+##### List Resource Fields
+
+| Field                   | Type   | Description                                                                                                                                    |
+|-------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.Name`                 | string | Name of the list resource (ex. `examplecloud_thing`)                                                                                           |
+| `.Type`                 | string | `List Resource`                                                                                                                                |
+| `.Description`          | string | List resource description                                                                                                                      |
+| `.HasExample`           | bool   | (Legacy) Is there an example file?                                                                                                             |
+| `.HasExamples`          | bool   | Are there example files? Always true if HasExample is true.                                                                                    |
+| `.ExampleFile`          | string | (Legacy) Path to the file with the terraform configuration example                                                                             |
+| `.ExampleFiles`         | string | Paths to the files with terraform configuration examples. Includes ExampleFile. The file extension for ExampleFiles should be `*.tfquery.hcl`. |
+| `.ProviderName`         | string | Canonical provider name (ex. `terraform-provider-random`)                                                                                      |
+| `.ProviderShortName`    | string | Short version of the rendered provider name (ex. `random`)                                                                                     |
+| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName`                                                      |
+| `.SchemaMarkdown`       | string | a Markdown formatted list resource Schema definition                                                                                           |
+
 #### Template Functions
 
 | Function        | Description                                                                                       |

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar

@@ -28,6 +28,7 @@ data-source "scaffolding_example" fallback template exists, creating template
 generating missing function content
 generating missing ephemeral resource content
 generating missing action content
+generating missing list resource content
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar

@@ -28,6 +28,7 @@ data-source "scaffolding_example" template exists, skipping
 generating missing function content
 generating missing ephemeral resource content
 generating missing action content
+generating missing list resource content
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar

@@ -26,6 +26,7 @@ generating new template for data-source "scaffolding_example"
 generating missing function content
 generating missing ephemeral resource content
 generating missing action content
+generating missing list resource content
 generating missing provider content
 generating new template for "terraform-provider-scaffolding"
 rendering static website

cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar

@@ -25,6 +25,7 @@ data-source "null_data_source" fallback template exists, creating template
 generating missing function content
 generating missing ephemeral resource content
 generating missing action content
+generating missing list resource content
 generating missing provider content
 provider "terraform-provider-null" template exists, skipping
 rendering static website

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar

@@ -21,6 +21,7 @@ generating missing function content
 generating new template for function "scaffolding"
 generating missing ephemeral resource content
 generating missing action content
+generating missing list resource content
 generating missing provider content
 generating new template for "terraform-provider-scaffolding"
 rendering static website

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar

@@ -12,6 +12,7 @@ cmpenv docs/resources/example.md expected-resource.md
 cmpenv docs/functions/example.md expected-function.md
 cmpenv docs/ephemeral-resources/example.md expected-ephemeral-resource.md
 cmpenv docs/actions/example.md expected-action.md
+cmpenv docs/list-resources/example.md expected-list-resource.md
 
 
 -- expected-output.txt --
@@ -30,6 +31,8 @@ generating missing ephemeral resource content
 ephemeral resource "scaffolding_example" fallback template exists, creating template
 generating missing action content
 action "scaffolding_example" fallback template exists, creating template
+generating missing list resource content
+list resource "scaffolding_example" fallback template exists, creating template
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website
@@ -40,6 +43,7 @@ rendering "data-sources/example.md.tmpl"
 rendering "ephemeral-resources/example.md.tmpl"
 rendering "functions/example.md.tmpl"
 rendering "index.md.tmpl"
+rendering "list-resources/example.md.tmpl"
 rendering "resources/example.md.tmpl"
 -- expected-action.md --
 # Data Fields
@@ -92,6 +96,59 @@ action "scaffolding_example" "example" {
   }
 }
 ```
+-- expected-list-resource.md --
+# Data Fields
+
+Name: scaffolding_example
+Type: List Resource
+Description: Example list resource
+HasExample: true
+ExampleFile: $WORK/examples/list-resources/scaffolding_example/list-resource.tfquery.hcl
+ProviderName: terraform-provider-scaffolding
+ProviderShortName: scaffolding
+RenderedProviderName: terraform-provider-scaffolding
+SchemaMarkdown: <!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `required_attr` (String) Example required attribute
+
+### Optional
+
+- `optional_attr` (String) Example optional attribute
+
+
+
+# Functions
+
+lower: list resource
+plainmarkdown: List Resource
+prefixlines: Prefix: List Resource
+split: [scaffolding example]
+title: List Resource
+trimspace: List Resource
+upper: LIST RESOURCE
+
+# Conditionals and File Functions
+
+printf tffile:
+## Example Usage
+
+{{tffile "$WORK/examples/list-resources/scaffolding_example/list-resource.tfquery.hcl"}}
+
+tffile:
+## Example Usage
+
+```terraform
+list "scaffolding_example" "example" {
+  provider = scaffolding
+
+  config {
+    required_attr = "some-value"
+  }
+}
+```
 -- expected-datasource.md --
 # Data Fields
 
@@ -365,6 +422,44 @@ resource "scaffolding_example" "example" {
   configurable_attribute = "some-value"
 }
 ```
+-- templates/list-resources.md.tmpl --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+Description: {{.Description}}
+HasExample: {{.HasExample}}
+ExampleFile: {{.ExampleFile}}
+ProviderName: {{.ProviderName}}
+ProviderShortName: {{.ProviderShortName}}
+RenderedProviderName: {{.RenderedProviderName}}
+SchemaMarkdown: {{.SchemaMarkdown}}
+
+# Functions
+
+lower: {{ .Type | lower }}
+plainmarkdown: {{ .Type | plainmarkdown }}
+prefixlines: {{ .Type | prefixlines "Prefix: " }}
+split: {{ split .Name "_" }}
+title: {{ .Type | title }}
+trimspace: {{ .Type | trimspace }}
+upper: {{ .Type | upper }}
+
+# Conditionals and File Functions
+
+printf tffile:
+{{ if .HasExample -}}
+## Example Usage
+
+{{ printf "{{tffile %q}}" .ExampleFile }}
+{{- end }}
+
+tffile:
+{{ if .HasExample -}}
+## Example Usage
+
+{{tffile .ExampleFile }}
+{{- end }}
 -- templates/actions.md.tmpl --
 # Data Fields
 
@@ -671,6 +766,14 @@ action "scaffolding_example" "example" {
     required_attr = "some-value"
   }
 }
+-- examples/list-resources/scaffolding_example/list-resource.tfquery.hcl --
+list "scaffolding_example" "example" {
+  provider = scaffolding
+
+  config {
+    required_attr = "some-value"
+  }
+}
 -- examples/data-sources/scaffolding_example/data-source.tf --
 data "scaffolding_example" "example" {
   configurable_attribute = "some-value"
@@ -722,6 +825,29 @@ resource "scaffolding_example" "example" {
                     "description_kind": "markdown"
                 }
             },
+            "list_resource_schemas": {
+                "scaffolding_example": {
+                    "version": 0,
+                    "block": {
+                        "attributes": {
+                            "required_attr": {
+                                "type": "string",
+                                "description": "Example required attribute",
+                                "description_kind": "plain",
+                                "required": true
+                            },
+                            "optional_attr": {
+                                "type": "string",
+                                "description": "Example optional attribute",
+                                "description_kind": "plain",
+                                "optional": true
+                            }
+                        },
+                        "description": "Example list resource",
+                        "description_kind": "plain"
+                    }
+                }
+            },
             "action_schemas": {
                 "scaffolding_example": {
                     "version": 0,