From 18bfe55780d3f0cd5f9c86c37e3941c80383ac92 Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Tue, 27 May 2025 02:57:38 -0700 Subject: [PATCH] Refactor documentation for parameter types and icons (#405) --- docs/data-sources/parameter.md | 14 +++++++------- docs/resources/agent.md | 2 +- docs/resources/app.md | 2 +- docs/resources/devcontainer.md | 7 +++++-- provider/agent.go | 2 +- provider/app.go | 2 +- provider/devcontainer.go | 2 +- provider/parameter.go | 14 +++++++------- 8 files changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/data-sources/parameter.md b/docs/data-sources/parameter.md index 934ae77a..ecba3929 100644 --- a/docs/data-sources/parameter.md +++ b/docs/data-sources/parameter.md @@ -145,13 +145,13 @@ data "coder_parameter" "home_volume_size" { - `description` (String) Describe what this parameter does. - `display_name` (String) The displayed name of the parameter as it will appear in the interface. - `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds. -- `form_type` (String) The type of this parameter. Must be one of: [radio, slider, input, dropdown, checkbox, switch, multi-select, tag-select, textarea, error]. +- `form_type` (String) The type of this parameter. Must be one of: `"radio"`, `"slider"`, `"input"`, `"dropdown"`, `"checkbox"`, `"switch"`, `"multi-select"`, `"tag-select"`, `"textarea"`, `"error"`. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution! - `option` (Block List) Each `option` block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option)) - `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order). - `styling` (String) JSON encoded string containing the metadata for controlling the appearance of this parameter in the UI. This option is purely cosmetic and does not affect the function of the parameter in terraform. -- `type` (String) The type of this parameter. Must be one of: `"number"`, `"string"`, `"bool"`, or `"list(string)"`. +- `type` (String) The type of this parameter. Must be one of: `"string"`, `"number"`, `"bool"`, `"list(string)"`. - `validation` (Block List, Max: 1) Validate the input of a parameter. (see [below for nested schema](#nestedblock--validation)) ### Read-Only @@ -179,13 +179,13 @@ Optional: Optional: -- `error` (String) An error message to display if the value breaks the validation rules. The following placeholders are supported: {max}, {min}, and {value}. -- `max` (Number) The maximum of a number parameter. -- `min` (Number) The minimum of a number parameter. +- `error` (String) An error message to display if the value breaks the validation rules. The following placeholders are supported: `{max}`, `{min}`, and `{value}`. +- `max` (Number) The maximum value of a number parameter. +- `min` (Number) The minimum value of a number parameter. - `monotonic` (String) Number monotonicity, either increasing or decreasing. - `regex` (String) A regex for the input parameter to match against. Read-Only: -- `max_disabled` (Boolean) Helper field to check if max is present -- `min_disabled` (Boolean) Helper field to check if min is present +- `max_disabled` (Boolean) Helper field to check if `max` is present +- `min_disabled` (Boolean) Helper field to check if `min` is present diff --git a/docs/resources/agent.md b/docs/resources/agent.md index 7df11e34..87ab4239 100644 --- a/docs/resources/agent.md +++ b/docs/resources/agent.md @@ -72,7 +72,7 @@ resource "kubernetes_pod" "dev" { ### Optional -- `api_key_scope` (String) Controls what API routes the agent token can access. Options: 'all' (full access) or 'no_user_data' (blocks /external-auth, /gitsshkey, and /gitauth routes) +- `api_key_scope` (String) Controls what API routes the agent token can access. Options: `all` (full access) or `no_user_data` (blocks `/external-auth`, `/gitsshkey`, and `/gitauth` routes) - `auth` (String) The authentication type the agent will use. Must be one of: `"token"`, `"google-instance-identity"`, `"aws-instance-identity"`, `"azure-instance-identity"`. - `connection_timeout` (Number) Time in seconds until the agent is marked as timed out when a connection with the server cannot be established. A value of zero never marks the agent as timed out. - `dir` (String) The starting directory when a user creates a shell session. Defaults to `"$HOME"`. diff --git a/docs/resources/app.md b/docs/resources/app.md index 338b1837..6be99cf3 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -66,7 +66,7 @@ resource "coder_app" "vim" { - `group` (String) The name of a group that this app belongs to. - `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck)) - `hidden` (Boolean) Determines if the app is visible in the UI (minimum Coder version: v2.16). -- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons here: https://github.com/coder/coder/tree/main/site/static/icon. Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. +- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls. - `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order). - `share` (String) Determines the level which the application is shared at. Valid levels are `"owner"` (default), `"authenticated"` and `"public"`. Level `"owner"` disables sharing on the app, so only the workspace owner can access it. Level `"authenticated"` shares the app with all authenticated users. Level `"public"` shares it with any user, including unauthenticated users. Permitted application sharing levels can be configured site-wide via a flag on `coder server` (Enterprise only). diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md index 93d5724b..06d7f6f3 100644 --- a/docs/resources/devcontainer.md +++ b/docs/resources/devcontainer.md @@ -3,12 +3,15 @@ page_title: "coder_devcontainer Resource - terraform-provider-coder" subcategory: "" description: |- - Define a Dev Container the agent should know of and attempt to autostart (minimum Coder version: v2.21). + Define a Dev Container the agent should know of and attempt to autostart. + -> This resource is only available in Coder v2.21 and later. --- # coder_devcontainer (Resource) -Define a Dev Container the agent should know of and attempt to autostart (minimum Coder version: v2.21). +Define a Dev Container the agent should know of and attempt to autostart. + +-> This resource is only available in Coder v2.21 and later. diff --git a/provider/agent.go b/provider/agent.go index ebd8fff5..32da2e58 100644 --- a/provider/agent.go +++ b/provider/agent.go @@ -85,7 +85,7 @@ func agentResource() *schema.Resource { Optional: true, Default: "all", ForceNew: true, - Description: "Controls what API routes the agent token can access. Options: 'all' (full access) or 'no_user_data' (blocks /external-auth, /gitsshkey, and /gitauth routes)", + Description: "Controls what API routes the agent token can access. Options: `all` (full access) or `no_user_data` (blocks `/external-auth`, `/gitsshkey`, and `/gitauth` routes)", ValidateFunc: validation.StringInSlice([]string{ "all", "no_user_data", diff --git a/provider/app.go b/provider/app.go index 213372b4..fb686794 100644 --- a/provider/app.go +++ b/provider/app.go @@ -88,7 +88,7 @@ func appResource() *schema.Resource { "icon": { Type: schema.TypeString, Description: "A URL to an icon that will display in the dashboard. View built-in " + - "icons here: https://github.com/coder/coder/tree/main/site/static/icon. Use a " + + "icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a " + "built-in icon with `\"${data.coder_workspace.me.access_url}/icon/\"`.", ForceNew: true, Optional: true, diff --git a/provider/devcontainer.go b/provider/devcontainer.go index 7d1fe0a4..81a31194 100644 --- a/provider/devcontainer.go +++ b/provider/devcontainer.go @@ -13,7 +13,7 @@ func devcontainerResource() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Define a Dev Container the agent should know of and attempt to autostart (minimum Coder version: v2.21).", + Description: "Define a Dev Container the agent should know of and attempt to autostart.\n\n-> This resource is only available in Coder v2.21 and later.", CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics { rd.SetId(uuid.NewString()) diff --git a/provider/parameter.go b/provider/parameter.go index de6e60f0..c8284da1 100644 --- a/provider/parameter.go +++ b/provider/parameter.go @@ -191,14 +191,14 @@ func parameterDataSource() *schema.Resource { Default: "string", Optional: true, ValidateFunc: validation.StringInSlice(toStrings(OptionTypes()), false), - Description: "The type of this parameter. Must be one of: `\"number\"`, `\"string\"`, `\"bool\"`, or `\"list(string)\"`.", + Description: fmt.Sprintf("The type of this parameter. Must be one of: `\"%s\"`.", strings.Join(toStrings(OptionTypes()), "\"`, `\"")), }, "form_type": { Type: schema.TypeString, Default: ParameterFormTypeDefault, Optional: true, ValidateFunc: validation.StringInSlice(toStrings(ParameterFormTypes()), false), - Description: fmt.Sprintf("The type of this parameter. Must be one of: [%s].", strings.Join(toStrings(ParameterFormTypes()), ", ")), + Description: fmt.Sprintf("The type of this parameter. Must be one of: `\"%s\"`.", strings.Join(toStrings(ParameterFormTypes()), "\"`, `\"")), }, "styling": { Type: schema.TypeString, @@ -286,22 +286,22 @@ func parameterDataSource() *schema.Resource { "min": { Type: schema.TypeInt, Optional: true, - Description: "The minimum of a number parameter.", + Description: "The minimum value of a number parameter.", }, "min_disabled": { Type: schema.TypeBool, Computed: true, - Description: "Helper field to check if min is present", + Description: "Helper field to check if `min` is present", }, "max": { Type: schema.TypeInt, Optional: true, - Description: "The maximum of a number parameter.", + Description: "The maximum value of a number parameter.", }, "max_disabled": { Type: schema.TypeBool, Computed: true, - Description: "Helper field to check if max is present", + Description: "Helper field to check if `max` is present", }, "monotonic": { Type: schema.TypeString, @@ -317,7 +317,7 @@ func parameterDataSource() *schema.Resource { "error": { Type: schema.TypeString, Optional: true, - Description: "An error message to display if the value breaks the validation rules. The following placeholders are supported: {max}, {min}, and {value}.", + Description: "An error message to display if the value breaks the validation rules. The following placeholders are supported: `{max}`, `{min}`, and `{value}`.", }, }, },