add list

Author: austinvalle

content/terraform-docs-common/docs/plugin/framework-benefits.mdx

@@ -259,5 +259,6 @@ Additional new and improved features in the framework include:
 - **Functions**: The framework supports provider-defined functions which are exposed for practitioner configurations.
 - **Ephemeral Resources**: The framework supports ephemeral resources which do not store data in the Terraform plan or state artifacts.
 - **Actions**: The framework supports actions which are side-effects that can be used to express workflows that don't strictly fit into CRUD resource management, such as disaster recovery or ad-hoc maintenance.
+- **List Resources**: The framework supports the list operation for a resource, which can be used with Terraform to discover unmanaged resources.
 
 Refer to [Framework Feature Comparison](/terraform/plugin/framework/migrating/benefits) for a continued list of features, details, and examples.

content/terraform-docs-common/docs/registry/providers/docs.mdx

@@ -34,7 +34,7 @@ If preferred you can choose to also invoke this manually for your provider. Once
 
 ## Format
 
-Provider documentation should be a directory of Markdown documents in the provider repository. Each Markdown document is rendered as a separate page. The directory should include a document for the provider index, a document for each resource, data source, ephemeral resource, action, function, and optional documents for any guides.
+Provider documentation should be a directory of Markdown documents in the provider repository. Each Markdown document is rendered as a separate page. The directory should include a document for the provider index, a document for each resource, data source, ephemeral resource, action, list resource, function, and optional documents for any guides.
 
 ### Directory Structure
 
@@ -47,6 +47,7 @@ Provider documentation should be a directory of Markdown documents in the provid
 | `docs/functions/`           | `<function>.md`           | Information on a provider function.                                                             |
 | `docs/ephemeral-resources/` | `<ephemeral-resource>.md` | Information for an Ephemeral Resource. Filename should not include a `<PROVIDER NAME>_` prefix. |
 | `docs/actions/`             | `<action>.md`             | Information for an action. Filename should not include a `<PROVIDER NAME>_` prefix.             |
+| `docs/list-resources/`      | `<list-resource>.md`      | Information for a List Resource. Filename should not include a `<PROVIDER NAME>_` prefix.       |
 
 -> **Note:** To support provider docs already formatted for publishing to [the website][terraform-io-providers], the Terraform Registry also supports docs in a `website/docs/` legacy directory with file extensions of `.html.markdown` or `.html.md`.
 
@@ -73,10 +74,10 @@ app/service documentation.
 * List any arguments for the provider block.
 ````
 
-#### Resource/Data Source/Ephemeral Resource/Action Headers
+#### Resource Type (managed, data source, ephemeral, etc.) Headers
 
 ````
-# <resource name> Resource/Data Source/Ephemeral Resource/Action
+# <resource name> <Resource Type>
 
 Description of what this resource does, with links to official
 app/service documentation.
@@ -156,11 +157,11 @@ If you start a paragraph with a special arrow-like sigil, it will become a color
 
 ## Navigation Hierarchy
 
-Provider docs are organized by category: functions, actions, ephemeral resources, resources, data sources, and guides. At a minimum, a provider must contain an index (`docs/index.md`) and at least one function, action, ephemeral resource, resource, or data source.
+Provider docs are organized by category: functions, actions, list resources, ephemeral resources, resources, data sources, and guides. At a minimum, a provider must contain an index (`docs/index.md`) and at least one function, action, ephemeral resource, list resource, resource, or data source.
 
 ### Typical Structure
 
-A provider named `example` with a resource and data source for `instance`, an ephemeral resource for `auth_token`, an action named `stop_instance`, and a function named `parse_instance_id`  would have these 5 files:
+A provider named `example` with a resource, list resource, and data source for `instance`, an ephemeral resource for `auth_token`, an action named `stop_instance`, and a function named `parse_instance_id`  would have these 5 files:
 
 ```
 docs/
@@ -173,6 +174,8 @@ docs/
         auth_token.md
     functions/
         parse_instance_id.md
+    list-resources/
+        instance.md
     resources/
         instance.md
 ```
@@ -186,6 +189,8 @@ After publishing this provider version, its page on the Terraform Registry would
   * parse_instance_id
 * Ephemeral Resources
   * example_auth_token
+* List Resources
+  * example_instance
 * Resources
   * example_instance
 * Data Sources
@@ -211,6 +216,8 @@ This would change the navigation hierarchy to the following:
     * parse_instance_id
   * Ephemeral Resources
     * example_auth_token
+  * List Resources
+    * example_instance
   * Resources
     * example_instance
   * Data Sources
@@ -240,6 +247,8 @@ docs/
         auth_token.md
     functions/
         parse_instance_id.md
+    list-resources/
+        instance.md
     resources/
         instance.md
 ```
@@ -263,12 +272,14 @@ The `page_title` is used (instead of the filename) for rendering the link to thi
   * parse_instance_id
 * Ephemeral Resources
   * example_auth_token
+* List Resources
+  * example_instance
 * Resources
   * example_instance
 * Data Sources
   * example_instance
 
-Guides are always rendered before resources, data sources, functions, actions, ephemeral resources, and any subcategories.
+Guides are always rendered before resources, data sources, functions, actions, ephemeral resources, list resources, and any subcategories.
 
 If a `page_title` attribute is not found, the title will default to the filename without the extension.
 
@@ -291,6 +302,8 @@ docs/
         auth_token.md
     functions/
         parse_instance_id.md
+    list-resources/
+        instance.md
     resources/
         instance.md
 ```
@@ -309,6 +322,8 @@ Assuming that these three guides have titles similar to their filenames, and the
   * parse_instance_id
 * Ephemeral Resources
   * example_auth_token
+* List Resources
+  * example_instance
 * Resources
   * example_instance
 * Data Sources
@@ -328,7 +343,7 @@ If you want to publish docs on the Terraform Registry that are not available on
 1. Expand the folder names to match the Terraform Registry's expected format:
    * Rename `docs/d/` to `docs/data-sources/`
    * Rename `docs/r/` to `docs/resources/`
-   * No changes necessary for `docs/functions/`, `docs/ephemeral-resources`, `docs/actions`, or `docs/guides`
+   * No changes necessary for `docs/functions/`, `docs/ephemeral-resources`, `docs/list-resources`, `docs/actions`, or `docs/guides`
 1. Change file suffixes from `.html.markdown` or `.html.md` to `.md`.
 
 [terraform-registry]: https://registry.terraform.io