docs: add missing code examples

docs/data-sources/external_auth.md

@@ -3,14 +3,28 @@
 page_title: "coder_external_auth Data Source - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services in a workspace. (e.g. gcloud, gh, docker, etc)
+  Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services https://coder.com/docs/admin/external-auth in a workspace. (e.g. Google Cloud, Github, Docker, etc.)
 ---
 
 # coder_external_auth (Data Source)
 
-Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services in a workspace. (e.g. gcloud, gh, docker, etc)
+Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.)
 
+## Example Usage
 
+```terraform
+provider "coder" {}
+
+
+data "coder_external_auth" "github" {
+  id = "github"
+}
+
+data "coder_external_auth" "azure-identity" {
+  id       = "azure-identiy"
+  optional = true
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/parameter.md

@@ -145,7 +145,7 @@ 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.
-- `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/<path>"`.
+- `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/<path>"`.
 - `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, Max: 64) 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).

docs/data-sources/provisioner.md

@@ -10,13 +10,33 @@ description: |-
 
 Use this data source to get information about the Coder provisioner.
 
+## Example Usage
 
+```terraform
+provider "coder" {}
+
+data "coder_provisioner" "dev" {}
+
+data "coder_workspace" "dev" {}
+
+resource "coder_agent" "main" {
+  arch = data.coder_provisioner.dev.arch
+  os   = data.coder_provisioner.dev.os
+  dir  = "/workspace"
+  display_apps {
+    vscode          = true
+    vscode_insiders = false
+    web_terminal    = true
+    ssh_helper      = false
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Read-Only
 
-- `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see https://pkg.go.dev/runtime#pkg-constants).
+- `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).
 - `id` (String) The ID of this resource.
-- `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see https://pkg.go.dev/runtime#pkg-constants).
+- `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).

docs/data-sources/workspace_owner.md

@@ -10,7 +10,38 @@ description: |-
 
 Use this data source to fetch information about the workspace owner.
 
+## Example Usage
 
+```terraform
+provider "coder" {}
+
+data "coder_workspace" "me" {}
+
+data "coder_workspace_owner" "me" {}
+
+resource "coder_agent" "dev" {
+  arch = "amd64"
+  os   = "linux"
+  dir  = local.repo_dir
+  env = {
+    OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token,
+  }
+}
+
+# Add git credentials from coder_workspace_owner
+resource "coder_env" "git_author_name" {
+  agent_id = coder_agent.agent_id
+  name     = "GIT_AUTHOR_NAME"
+  value    = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
+}
+
+resource "coder_env" "git_author_email" {
+  agent_id = var.agent_id
+  name     = "GIT_AUTHOR_EMAIL"
+  value    = data.coder_workspace_owner.me.email
+  count    = data.coder_workspace_owner.me.email != "" ? 1 : 0
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/resources/env.md

@@ -10,7 +10,29 @@ description: |-
 
 Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the "coder_agent" resource.
 
-
+## Example Usage
+
+```terraform
+data "coder_workspace" "me" {}
+
+resource "coder_agent" "dev" {
+  os   = "linux"
+  arch = "amd64"
+  dir  = "/workspace"
+}
+
+resource "coder_env" "welcome_message" {
+  agent_id = coder_agent.dev.id
+  name     = "WELCOME_MESSAGE"
+  value    = "Welcome to your Coder workspace!"
+}
+
+resource "coder_env" "internal_api_url" {
+  agent_id = coder_agent.dev.id
+  name     = "INTERNAL_API_URL"
+  value    = "https://api.internal.company.com/v1"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/resources/script.md

@@ -3,14 +3,69 @@
 page_title: "coder_script Resource - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Use this resource to run a script from an agent.
+  Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.
 ---
 
 # coder_script (Resource)
 
-Use this resource to run a script from an agent.
+Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.
 
+## Example Usage
 
+```terraform
+data "coder_workspace" "me" {}
+
+resource "coder_agent" "dev" {
+  os   = "linux"
+  arch = "amd64"
+  dir  = "/workspace"
+}
+
+resource "coder_script" "dotfiles" {
+  agent_id     = coder_agent.dev.agent_id
+  display_name = "Dotfiles"
+  icon         = "/icon/dotfiles.svg"
+  run_on_start = true
+  script = templatefile("~/get_dotfiles.sh", {
+    DOTFILES_URI : var.dotfiles_uri,
+    DOTFILES_USER : var.dotfiles_user
+  })
+}
+
+resource "coder_script" "code-server" {
+  agent_id           = coder_agent.dev.agent_id
+  display_name       = "code-server"
+  icon               = "/icon/code.svg"
+  run_on_start       = true
+  start_blocks_login = true
+  script = templatefile("./install-code-server.sh", {
+    LOG_PATH : "/tmp/code-server.log"
+  })
+}
+
+resource "coder_script" "nightly_sleep_reminder" {
+  agent_id     = coder_agent.dev.agent_id
+  display_name = "Nightly update"
+  icon         = "/icon/database.svg"
+  cron         = "0 22 * * *"
+  script       = <<EOF
+    #!/bin/sh
+    echo "Running nightly update"
+    sudo apt-get install
+  EOF
+}
+
+resource "coder_script" "shutdown" {
+  agent_id     = coder_agent.dev.id
+  display_name = "Stop daemon server"
+  run_on_stop  = true
+  icon         = "/icons/memory.svg"
+  script       = <<EOF
+    #!/bin/sh 
+    kill $(lsof -i :3002 -t) >/tmp/pid.log 2>&1 &
+  EOF
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

examples/data-sources/coder_external_auth/data-source.tf

@@ -0,0 +1,11 @@
+provider "coder" {}
+
+
+data "coder_external_auth" "github" {
+  id = "github"
+}
+
+data "coder_external_auth" "azure-identity" {
+  id       = "azure-identiy"
+  optional = true
+}

examples/data-sources/coder_provisioner/data-source.tf

@@ -0,0 +1,17 @@
+provider "coder" {}
+
+data "coder_provisioner" "dev" {}
+
+data "coder_workspace" "dev" {}
+
+resource "coder_agent" "main" {
+  arch = data.coder_provisioner.dev.arch
+  os   = data.coder_provisioner.dev.os
+  dir  = "/workspace"
+  display_apps {
+    vscode          = true
+    vscode_insiders = false
+    web_terminal    = true
+    ssh_helper      = false
+  }
+}

examples/data-sources/coder_workspace_owner/data-source.tf

@@ -0,0 +1,28 @@
+provider "coder" {}
+
+data "coder_workspace" "me" {}
+
+data "coder_workspace_owner" "me" {}
+
+resource "coder_agent" "dev" {
+  arch = "amd64"
+  os   = "linux"
+  dir  = local.repo_dir
+  env = {
+    OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token,
+  }
+}
+
+# Add git credentials from coder_workspace_owner
+resource "coder_env" "git_author_name" {
+  agent_id = coder_agent.agent_id
+  name     = "GIT_AUTHOR_NAME"
+  value    = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
+}
+
+resource "coder_env" "git_author_email" {
+  agent_id = var.agent_id
+  name     = "GIT_AUTHOR_EMAIL"
+  value    = data.coder_workspace_owner.me.email
+  count    = data.coder_workspace_owner.me.email != "" ? 1 : 0
+}

examples/resources/coder_env/resource.tf

@@ -0,0 +1,19 @@
+data "coder_workspace" "me" {}
+
+resource "coder_agent" "dev" {
+  os   = "linux"
+  arch = "amd64"
+  dir  = "/workspace"
+}
+
+resource "coder_env" "welcome_message" {
+  agent_id = coder_agent.dev.id
+  name     = "WELCOME_MESSAGE"
+  value    = "Welcome to your Coder workspace!"
+}
+
+resource "coder_env" "internal_api_url" {
+  agent_id = coder_agent.dev.id
+  name     = "INTERNAL_API_URL"
+  value    = "https://api.internal.company.com/v1"
+}

examples/resources/coder_script/resource.tf

@@ -0,0 +1,52 @@
+data "coder_workspace" "me" {}
+
+resource "coder_agent" "dev" {
+  os   = "linux"
+  arch = "amd64"
+  dir  = "/workspace"
+}
+
+resource "coder_script" "dotfiles" {
+  agent_id     = coder_agent.dev.agent_id
+  display_name = "Dotfiles"
+  icon         = "/icon/dotfiles.svg"
+  run_on_start = true
+  script = templatefile("~/get_dotfiles.sh", {
+    DOTFILES_URI : var.dotfiles_uri,
+    DOTFILES_USER : var.dotfiles_user
+  })
+}
+
+resource "coder_script" "code-server" {
+  agent_id           = coder_agent.dev.agent_id
+  display_name       = "code-server"
+  icon               = "/icon/code.svg"
+  run_on_start       = true
+  start_blocks_login = true
+  script = templatefile("./install-code-server.sh", {
+    LOG_PATH : "/tmp/code-server.log"
+  })
+}
+
+resource "coder_script" "nightly_sleep_reminder" {
+  agent_id     = coder_agent.dev.agent_id
+  display_name = "Nightly update"
+  icon         = "/icon/database.svg"
+  cron         = "0 22 * * *"
+  script       = <<EOF
+    #!/bin/sh
+    echo "Running nightly update"
+    sudo apt-get install
+  EOF
+}
+
+resource "coder_script" "shutdown" {
+  agent_id     = coder_agent.dev.id
+  display_name = "Stop daemon server"
+  run_on_stop  = true
+  icon         = "/icons/memory.svg"
+  script       = <<EOF
+    #!/bin/sh 
+    kill $(lsof -i :3002 -t) >/tmp/pid.log 2>&1 &
+  EOF
+}

provider/externalauth.go

@@ -15,7 +15,7 @@ func externalAuthDataSource() *schema.Resource {
 	return &schema.Resource{
 		SchemaVersion: 1,
 
-		Description: "Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services in a workspace. (e.g. gcloud, gh, docker, etc)",
+		Description: "Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.)",
 		ReadContext: func(ctx context.Context, rd *schema.ResourceData, i interface{}) diag.Diagnostics {
 			id, ok := rd.Get("id").(string)
 			if !ok || id == "" {

provider/parameter.go

@@ -220,7 +220,7 @@ func parameterDataSource() *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/<path>\"`.",
 				ForceNew: true,
 				Optional: true,

provider/provisioner.go

@@ -29,12 +29,12 @@ func provisionerDataSource() *schema.Resource {
 			"os": {
 				Type:        schema.TypeString,
 				Computed:    true,
-				Description: "The operating system of the host. This exposes `runtime.GOOS` (see https://pkg.go.dev/runtime#pkg-constants).",
+				Description: "The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).",
 			},
 			"arch": {
 				Type:        schema.TypeString,
 				Computed:    true,
-				Description: "The architecture of the host. This exposes `runtime.GOARCH` (see https://pkg.go.dev/runtime#pkg-constants).",
+				Description: "The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).",
 			},
 		},
 	}

provider/script.go

@@ -17,7 +17,7 @@ func scriptResource() *schema.Resource {
 	return &schema.Resource{
 		SchemaVersion: 1,
 
-		Description: "Use this resource to run a script from an agent.",
+		Description: "Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.",
 		CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics {
 			rd.SetId(uuid.NewString())
 			runOnStart, _ := rd.Get("run_on_start").(bool)