[chore] Update provider docs (#27)

docs/data-sources/folders.md

@@ -1,14 +1,12 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_folders Data Source - retool"
-subcategory: ""
+page_title: "Data Source: retool_folders"
 description: |-
-  
+  Folders data source allows you to retrieve a list of folders in Retool.
 ---
 
-# retool_folders (Data Source)
-
+# Data Source: retool_folders
 
+Folders data source allows you to retrieve a list of folders in Retool.
 
 ## Example Usage
 
@@ -33,8 +31,10 @@ output "all_folders" {
 Read-Only:
 
 - `folder_type` (String) The type of the folder: (app|file|resource|workflow).
-- `id` (String) The id of the folder. Currently this is the same as legacy_id but will be different in the future.
+- `id` (String) The id of the folder.
 - `is_system_folder` (Boolean) Whether the folder is a system folder.
 - `legacy_id` (String) The legacy id of the folder.
 - `name` (String) The name of the folder.
 - `parent_folder_id` (String) The id of the parent folder.
+
+

docs/index.md

@@ -1,14 +1,17 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool Provider"
-subcategory: ""
+page_title: "Provider: Retool"
 description: |-
-  
+  The Retool provider can be used to interact with 
+  [Retool Platform API](https://docs.retool.com/org-users/quickstart#retool-api) to configure your Retool instance and Spaces.
 ---
 
-# retool Provider
+# Retool Provider
 
+Retool Terraform provider helps you configure Spaces, SSO, Source Control, permissions and other settings on 
+self-hosted Retool instance or Retool Cloud organization using [Retool Platform API](https://docs.retool.com/org-users/quickstart#retool-api).
 
+## Prerequisites
+Your [Retool plan](https://retool.com/pricing) should support Platform APIs. You'll need to create an API token on **Settings > Retool API** .
 
 ## Example Usage
 
@@ -18,8 +21,41 @@ provider "retool" {
   scheme       = "https"
   access_token = "your-access-token"
 }
+
+
+# Create an app folder
+resource "retool_folder" "production_apps" {
+  name        = "Production Apps"
+  folder_type = "app"
+}
+
+# Create a permission group
+resource "retool_group" "production_apps_users" {
+  name = "Production Apps Users"
+}
+
+# Grant "use" permissions on the folder to the permission group
+resource "retool_permissions" "production_apps_users" {
+  subject = {
+    type = "group"
+    id   = retool_folder.production_apps_users.id
+  }
+  permissions = [
+    {
+      object = {
+        type = "folder"
+        id   = retool_folder.production_apps.id
+      }
+      access_level = "use"
+    }
+  ]
+}
 ```
 
+~> Hard-coding credentials into any Terraform configuration is not recommended, and risks secret leakage should this
+file ever be committed to a public version control system. See [Environment Variables](#environment-variables) for a
+better alternative.
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
@@ -28,3 +64,51 @@ provider "retool" {
 - `access_token` (String, Sensitive) The access token for the Retool API
 - `host` (String) The host of the Retool instance, organization or Space, e.g. 'example.retool.com'
 - `scheme` (String) The scheme of the Retool instance, e.g. 'https'
+
+## Environment Variables
+
+You can provide your credentials via the `RETOOL_HOST`, `RETOOL_SCHEME` and `RETOOL_ACCESS_TOKEN`
+environment variables, respectively.
+
+```terraform
+provider "retool" {
+}
+
+
+# Create an app folder
+resource "retool_folder" "production_apps" {
+  name        = "Production Apps"
+  folder_type = "app"
+}
+
+# Create a permission group
+resource "retool_group" "production_apps_users" {
+  name = "Production Apps Users"
+}
+
+# Grant "use" permissions on the folder to the permission group
+resource "retool_permissions" "production_apps_users" {
+  subject = {
+    type = "group"
+    id   = retool_folder.production_apps_users.id
+  }
+  permissions = [
+    {
+      object = {
+        type = "folder"
+        id   = retool_folder.production_apps.id
+      }
+      access_level = "use"
+    }
+  ]
+}
+```
+
+### Example Usage
+
+```shell
+RETOOL_HOST="your-retool-instance.com" \
+RETOOL_SCHEME="https" \
+RETOOL_ACCESS_TOKEN="your-access-token" \
+terraform plan
+```

docs/resources/folder.md

@@ -1,14 +1,12 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_folder Resource - retool"
-subcategory: ""
+page_title: "Resource: retool_folder"
 description: |-
-  
+  Folder resource allows you to create and manage folders in Retool.
 ---
 
-# retool_folder (Resource)
-
+# Resource: retool_folder
 
+Folder resource allows you to create and manage folders in Retool.
 
 ## Example Usage
 

docs/resources/group.md

@@ -1,14 +1,14 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_group Resource - retool"
-subcategory: ""
+page_title: "Resource: retool_group"
 description: |-
-  
+  A group is a collection of users that can be granted access to folders, apps, resources, and workflows.
+  Managing group membership via Terraform provider is currently not supported. You can assign users to groups using SSO.
 ---
 
-# retool_group (Resource)
-
+# Resource: retool_group
 
+A group is a collection of users that can be granted access to folders, apps, resources, and workflows. 
+		Managing group membership via Terraform provider is currently not supported. You can assign users to groups using SSO.
 
 ## Example Usage
 
@@ -39,10 +39,10 @@ resource "retool_group" "example" {
 - `account_details_access` (Boolean) Whether the group has access to account details.
 - `audit_log_access` (Boolean) Whether the group has access to the audit log.
 - `landing_page_app_id` (String) The app ID of the landing page.
-- `universal_app_access` (String) The universal app access level for the group. This denotes the access level that this group has for all apps.
-- `universal_query_library_access` (String) Level of access that the group has to the Query Library.
-- `universal_resource_access` (String) The universal resource access level for the group. This denotes the access level that this group has for all resources.
-- `universal_workflow_access` (String) The universal workflow access level for the group. This denotes the access level that this group has for all workflows.
+- `universal_app_access` (String) The universal app access level for the group. This denotes the access level that this group has for all apps. Accepted values: none|use|edit|own
+- `universal_query_library_access` (String) Level of access that the group has to the Query Library. Accepted values: none|use|edit
+- `universal_resource_access` (String) The universal resource access level for the group. This denotes the access level that this group has for all resources. Accepted values: none|use|edit|own
+- `universal_workflow_access` (String) The universal workflow access level for the group. This denotes the access level that this group has for all workflows. Accepted values: none|use|edit|own
 - `unpublished_release_access` (Boolean) Whether the group has access to unpublished releases.
 - `usage_analytics_access` (Boolean) Whether the group has access to usage analytics.
 - `user_list_access` (Boolean) Whether the group has access to the user list.

docs/resources/permissions.md

@@ -1,14 +1,12 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_permissions Resource - retool"
-subcategory: ""
+page_title: "Resource: retool_permissions"
 description: |-
-  
+  Permissions resource can be used to grant a user or a permission group access to an object: app, folder, resource or resource configuration.
 ---
 
-# retool_permissions (Resource)
-
+# Resource: retool_permissions
 
+Permissions resource can be used to grant a user or a permission group access to an object: app, folder, resource or resource configuration.
 
 ## Example Usage
 
@@ -43,7 +41,7 @@ resource "retool_permissions" "test_permissions" {
 
 Required:
 
-- `access_level` (String) The access level of the permission.
+- `access_level` (String) The access level of the permission. Accepted values are 'own', 'edit', 'use'.
 - `object` (Attributes) Permission object (that the action is performed on). (see [below for nested schema](#nestedatt--permissions--object))
 
 <a id="nestedatt--permissions--object"></a>
@@ -63,3 +61,5 @@ Required:
 
 - `id` (String) The ID of the subject.
 - `type` (String) The type of the subject - user or group.
+
+

docs/resources/source_control.md

@@ -1,14 +1,12 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_source_control Resource - retool"
-subcategory: ""
+page_title: "Resource: retool_source_control"
 description: |-
-  
+  Source Control resource allows you to connect Retool to a source control provider.
 ---
 
-# retool_source_control (Resource)
-
+# Resource: retool_source_control
 
+Source Control resource allows you to connect Retool to a source control provider.
 
 ## Example Usage
 
@@ -113,3 +111,5 @@ Required:
 - `project_access_token` (String, Sensitive) The GitLab project access token to authenticate to the GitLab API.
 - `project_id` (String) The numerical project ID for your GitLab project. Find this ID listed below the project's name on the project's homepage.
 - `url` (String) Your base GitLab URL. On GitLab Cloud, this is always https://gitlab.com. On GitLab self-managed, this is the URL where your instance is hosted.
+
+

docs/resources/source_control_settings.md

@@ -1,14 +1,12 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_source_control_settings Resource - retool"
-subcategory: ""
+page_title: "Resource: retool_source_control_settings"
 description: |-
-  
+  Source Control settings resource allows you to fine-tune how Source Control works in Retool.
 ---
 
-# retool_source_control_settings (Resource)
-
+# Resource: retool_source_control_settings
 
+Source Control settings resource allows you to fine-tune how Source Control works in Retool.
 
 ## Example Usage
 
@@ -30,3 +28,5 @@ resource "retool_source_control_settings" "scm_settings" {
 - `custom_pull_request_template` (String) Pull requests created from Retool will use the template specified.
 - `custom_pull_request_template_enabled` (Boolean) When enabled, Retool will use the template specified to create pull requests. Defaults to false.
 - `version_control_locked` (Boolean) When set to true, creates a read-only instance of Retool, where app editing is disabled. Defaults to false.
+
+

docs/resources/space.md

@@ -1,14 +1,12 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_space Resource - retool"
-subcategory: ""
+page_title: "Resource: retool_space"
 description: |-
-  
+  Space resource allows you to create and manage Spaces in Retool. The provider must be configured using the hostname of the admin Space.
 ---
 
-# retool_space (Resource)
-
+# Resource: retool_space
 
+Space resource allows you to create and manage Spaces in Retool. The provider must be configured using the hostname of the admin Space.
 
 ## Example Usage
 
@@ -21,7 +19,9 @@ resource "retool_space" "test_space" {
 resource "retool_space" "test_space_with_create_options" {
   name   = "Test Space with creation options"
   domain = "space2.example.com"
-  create_options = { # Note that changing any of these values will result in the old space being deleted and a new space being created
+  create_options = {
+    # Note that changing any of these values will result in the old space being deleted 
+    # and a new space being created
     copy_sso_settings                 = true
     copy_branding_and_themes_settings = true
     create_admin_user                 = false
@@ -55,3 +55,5 @@ Optional:
 - `copy_sso_settings` (Boolean) Copy SSO settings from the admin Space.
 - `create_admin_user` (Boolean) Create an admin user in the new space for the creator instead of just sending out an invite.
 - `users_to_copy_as_admins` (List of String) List of emails of users from the admin space that need to be added to the new space as admins.
+
+

docs/resources/sso.md

@@ -1,14 +1,12 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "retool_sso Resource - retool"
-subcategory: ""
+page_title: "Resource: retool_sso"
 description: |-
-  
+  SSO settings resource allows you to configure Single Sign-On in Retool.
 ---
 
-# retool_sso (Resource)
-
+# Resource: retool_sso
 
+SSO settings resource allows you to configure Single Sign-On in Retool.
 
 ## Example Usage
 
@@ -132,3 +130,5 @@ Read-Only:
 
 - `encrypted_server_certificate` (String, Sensitive) Encrypted Server Certificate
 - `encrypted_server_key` (String, Sensitive) Encrypted Server Key
+
+

examples/provider/provider.tf

@@ -3,3 +3,32 @@ provider "retool" {
   scheme       = "https"
   access_token = "your-access-token"
 }
+
+
+# Create an app folder
+resource "retool_folder" "production_apps" {
+  name        = "Production Apps"
+  folder_type = "app"
+}
+
+# Create a permission group
+resource "retool_group" "production_apps_users" {
+  name = "Production Apps Users"
+}
+
+# Grant "use" permissions on the folder to the permission group
+resource "retool_permissions" "production_apps_users" {
+  subject = {
+    type = "group"
+    id   = retool_folder.production_apps_users.id
+  }
+  permissions = [
+    {
+      object = {
+        type = "folder"
+        id   = retool_folder.production_apps.id
+      }
+      access_level = "use"
+    }
+  ]
+}