Docs and examples

docs/data-sources/dns_zone.md

@@ -10,7 +10,14 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# Read-only data source for a Netlify DNS zone.
+data "netlify_dns_zone" "example" {
+  name = "example.com"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/site.md

@@ -10,7 +10,20 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# Looking up a site by its team slug and site name
+data "netlify_site" "blog" {
+  team_slug = "my-team-slug"
+  name      = "Blog"
+}
+
+# Looking up a blog by its ID
+data "netlify_site" "blog" {
+  id = "12345667-0000-0000-0000-abcdef012345"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/sites.md

@@ -10,7 +10,14 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# List all sites in a team, by the team's slug
+data "netlify_sites" "team" {
+  team_slug = "my-team-slug"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/team.md

@@ -10,7 +10,19 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# Looking up a team by its slug
+data "netlify_team" "team" {
+  slug = "my-team-slug"
+}
+
+# Looking up a team by its ID
+data "netlify_team" "team" {
+  id = "6600abcdef1234567890abcd"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/index.md

@@ -7,12 +7,75 @@ description: |-
 
 # Netlify Provider
 
-The Netlify provider provides resources to interact with a Netlify account.
+The Netlify provider provides resources to manage Netlify resources like site configuration, environment variables, and Advanced Web Security features.
+
+## Authentication
+
+To use the provider, you will need a [personal access token](https://docs.netlify.com/api/get-started/#authentication).
+You can create a new token in the [Netlify app](https://app.netlify.com/user/applications#personal-access-tokens).
+
+You can expose the token as an environment variable:
+```bash
+export NETLIFY_API_TOKEN="your-personal-access-token"
+```
+
+Or by creating a Terraform variable:
+```terraform
+variable "netlify_api_token" {
+  type = string
+}
+
+provider "netlify" {
+  token = var.netlify_api_token
+}
+```
+and setting the variable's value as an environment variable (`TF_VAR_netlify_api_token`).
+
+## Example Usage
+
+```terraform
+variable "netlify_api_token" {
+  type = string
+}
+
+terraform {
+  required_providers {
+    netlify = {
+      source = "registry.terraform.io/netlify/netlify"
+    }
+  }
+}
+
+provider "netlify" {
+  token = var.netlify_api_token
+}
+
+data "netlify_team" "team" {
+  slug = "your-team-slug"
+}
+
+data "netlify_site" "blog" {
+  team_slug = data.netlify_team.team.slug
+  name      = "blog"
+}
+
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Optional
 
 - `endpoint` (String) Defaults to: https://api.netlify.com
-- `token` (String, Sensitive) Read: https://docs.netlify.com/api/get-started/
+- `token` (String, Sensitive) Read: https://docs.netlify.com/api/get-started/#authentication , will use the `NETLIFY_API_TOKEN` environment variable if not set.

docs/resources/dns_record.md

@@ -3,22 +3,46 @@
 page_title: "netlify_dns_record Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Netlify DNS record. Read more https://docs.netlify.com/domains-https/netlify-dns/
 ---
 
 # netlify_dns_record (Resource)
 
+Netlify DNS record. [Read more](https://docs.netlify.com/domains-https/netlify-dns/)
 
+## Example Usage
 
+```terraform
+resource "netlify_dns_record" "www" {
+  type     = "A"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "www.example.com"
+  value    = "198.18.0.50"
+}
 
+resource "netlify_dns_record" "calendar" {
+  type     = "CNAME"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "calendar.example.com"
+  value    = "ghs.googlehosted.com."
+}
+
+resource "netlify_dns_record" "mx" {
+  type     = "MX"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "example.com"
+  value    = "smtp.google.com"
+  priority = 1
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `hostname` (String)
-- `type` (String)
+- `hostname` (String) The hostname for the DNS record. For example, `www.example.com`.
+- `type` (String) One of A, AAAA, ALIAS, CAA, CNAME, MX, NS, SPF, or TXT
 - `value` (String)
 - `zone_id` (String)
 
@@ -33,3 +57,12 @@ description: |-
 
 - `id` (String) The ID of this resource.
 - `last_updated` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a DNS record by its zone ID and its record ID
+terraform import netlify_dns_record.www_example 6600abcdef1234567890abcd:6600abcdef1234567890abcd
+```

docs/resources/dns_zone.md

@@ -3,14 +3,24 @@
 page_title: "netlify_dns_zone Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Netlify DNS zone. Read more https://docs.netlify.com/domains-https/netlify-dns/
 ---
 
 # netlify_dns_zone (Resource)
 
+Netlify DNS zone. [Read more](https://docs.netlify.com/domains-https/netlify-dns/)
 
+## Example Usage
 
-
+```terraform
+resource "netlify_dns_zone" "example" {
+  team_slug = data.netlify_team.team.slug
+  name      = "example.com"
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -40,3 +50,12 @@ Read-Only:
 - `name` (String)
 - `registered_at` (String)
 - `renewal_price` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a DNS zone by its ID
+terraform import netlify_dns_zone.example 6600abcdef1234567890abcd
+```

docs/resources/environment_variable.md

@@ -3,14 +3,87 @@
 page_title: "netlify_environment_variable Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Environment variables for Netlify sites. Read more https://docs.netlify.com/environment-variables/overview/
 ---
 
 # netlify_environment_variable (Resource)
 
-
-
-
+Environment variables for Netlify sites. [Read more](https://docs.netlify.com/environment-variables/overview/)
+
+## Example Usage
+
+```terraform
+# Site-level environment variable, note that both team_id and site_id are specified
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+
+# Team-level environment variable, note that only team_id is specified
+# Not supported on all Netlify plans
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+
+# Secret environment variable
+# Not supported on all Netlify plans
+resource "netlify_environment_variable" "astro_studio_app_token" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_STUDIO_APP_TOKEN"
+  secret_values = [
+    {
+      value   = "token-here",
+      context = "all",
+    }
+  ]
+}
+
+# Values that differ by context
+resource "netlify_environment_variable" "astro_studio_app_token" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_STUDIO_APP_TOKEN"
+  secret_values = [
+    {
+      value   = "token-here",
+      context = "production",
+    },
+    {
+      value   = "non-prod-token-here",
+      context = "deploy-preview",
+    }
+  ]
+}
+
+# A variable that's only available in some scopes, e.g. in builds
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  scopes  = ["builds"]
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -22,7 +95,7 @@ description: |-
 
 ### Optional
 
-- `scopes` (Set of String)
+- `scopes` (Set of String) One or more of builds, functions, runtime, and post-processing
 - `secret_values` (Attributes Set) (see [below for nested schema](#nestedatt--secret_values))
 - `site_id` (String)
 - `values` (Attributes Set) (see [below for nested schema](#nestedatt--values))
@@ -36,7 +109,7 @@ description: |-
 
 Required:
 
-- `context` (String)
+- `context` (String) One of all, dev, branch-deploy, deploy-preview, production, or branch
 - `value` (String, Sensitive)
 
 Optional:
@@ -49,9 +122,21 @@ Optional:
 
 Required:
 
-- `context` (String)
+- `context` (String) One of all, dev, branch-deploy, deploy-preview, production, or branch
 - `value` (String)
 
 Optional:
 
 - `context_parameter` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a team-level environment variable using the team ID and the environment variable key
+terraform import netlify_environment_variable.name 6600abcdef1234567890abcd:ASTRO_DATABASE_FILE
+
+# Import a site-level environment variable using the team ID, the site ID, and the environment variable key
+terraform import netlify_environment_variable.name 6600abcdef1234567890abcd:12345667-0000-0000-0000-abcdef012345:ASTRO_DATABASE_FILE
+```