SUP-1293 Generate docs from code (#397)

* Add github.com/hashicorp/terraform-plugin-docs

* Add make target for docs

* Add CI step to check docs are up to date

* Change directory in docker compose

* Update docs for provider

* Update docs for cluster data source

* Update docs for meta data source

* Remove unused examples files

* Update docs for organization data source

* Update docs for pipeline data source

* Update docs for team data source

* Update agent token resource docs

* Update docs for cluster resource

* Update docs for cluster agent token resource

* Update docs for cluster queue resource

* Update docs for organization resource

* Update pipeline resource docs

* Add elastic ci stack guide

* Update docs on pipeline schedule resource

* Update pipeline_team resource docs

* Update docs for team resource

* Update docs for team member resource

* Update docs for test suite resource

* Update test suite team resource docs

* Update changelog

* Add import files for cluster/cluster queue

* Add extra doc note to elastic stack guide

* Update local terraform version in CI

* Print terraform version in docs step

* Change working dir for CI

* Undo changes to docker/CI

* Add v1.0 upgrade guide

* Add comments to examples

* Fix typo

* Update elastic stack guide title

CHANGELOG.md

@@ -10,9 +10,10 @@ All notable changes to this project will be documented in this file.
 - retryContextError util resource switch [[PR #394](https://github.com/buildkite/terraform-provider-buildkite/pull/394)] @james2791
 - Added `build_pull_request_ready_for_review` to pipeline resource docs/examples/tests [[PR #396](https://github.com/buildkite/terraform-provider-buildkite/pull/396)] @james2791
 - SUP-1370 Update to protocol v6 [[PR #400](https://github.com/buildkite/terraform-provider-buildkite/pull/400)] @jradtilbrook
+- SUP-1293 Generate docs from code [[PR #397](https://github.com/buildkite/terraform-provider-buildkite/pull/397)] @jradtilbrook
 
 The `team` block from the `buildkite_pipeline` resource has been removed. Please use the resource `buildkite_pipeline_team` to create and manage team configuration in a pipeline.
-   
+
 ## [v0.27.0](https://github.com/buildkite/terraform-provider-buildkite/compare/v0.26.0...v0.27.0)
 
 - SUP-805: SUP-805: Team resource retries [[PR #360](https://github.com/buildkite/terraform-provider-buildkite/pull/360)] @james2791

Makefile

@@ -3,6 +3,10 @@ default: build
 build:
 	go build -o terraform-provider-buildkite -ldflags="-s -w -X main.version=$(shell git describe --tag)" .
 
+.PHONY: docs
+docs:
+	go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
+
 fmt:
 	go fmt ./...
 

buildkite/data_source_cluster.go

@@ -99,16 +99,18 @@ func (c *clusterDatasource) Read(ctx context.Context, req datasource.ReadRequest
 
 func (*clusterDatasource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "Look up a cluster by name.",
+		MarkdownDescription: "Use this data source to retrieve a cluster by name. You can find out more about clusters in the Buildkite [documentation](https://buildkite.com/docs/clusters/overview).",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The GraphQL ID of the cluster.",
 			},
 			"uuid": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The UUID of the cluster",
 			},
 			"name": schema.StringAttribute{
-				MarkdownDescription: "The name of the Cluster to find.",
+				MarkdownDescription: "The name of the cluster to retrieve.",
 				Required:            true,
 			},
 			"description": schema.StringAttribute{

buildkite/data_source_meta.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"sort"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
 	"github.com/hashicorp/terraform-plugin-framework/types"
@@ -63,13 +64,19 @@ func (m *metaDatasource) Read(ctx context.Context, req datasource.ReadRequest, r
 
 func (*metaDatasource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "Find source IP addresses that Buildkite may use to send external requests to.",
+		MarkdownDescription: heredoc.Doc(`
+		Use this data source to look up the source IP addresses that Buildkite may use to send external requests,
+		including webhooks and API calls to source control systems (like GitHub Enterprise Server and BitBucket Server).
+
+		More info in the Buildkite [documentation](https://buildkite.com/docs/apis/rest-api/meta).
+		`),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "Fixed value: `https://api.buildkite.com/v2/meta`.",
 			},
 			"webhook_ips": schema.ListAttribute{
-				MarkdownDescription: "List of IPs in CIDR format",
+				MarkdownDescription: "List of IPs in CIDR format.",
 				Computed:            true,
 				ElementType:         types.StringType,
 			},

buildkite/data_source_organization.go

@@ -68,17 +68,20 @@ func (o *organizationDatasource) Read(ctx context.Context, req datasource.ReadRe
 
 func (*organizationDatasource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "Look up organization settings.",
+		MarkdownDescription: "Use this data source to look up the organization settings.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The GraphQL ID of the organization.",
 			},
 			"uuid": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The UUID of the organization.",
 			},
 			"allowed_api_ip_addresses": schema.ListAttribute{
-				Computed:    true,
-				ElementType: types.StringType,
+				Computed:            true,
+				ElementType:         types.StringType,
+				MarkdownDescription: "List of IP addresses in CIDR format that are allowed to access the Buildkite API for this organization.",
 			},
 		},
 	}

buildkite/data_source_pipeline.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"log"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
 	"github.com/hashicorp/terraform-plugin-framework/types"
@@ -42,9 +43,15 @@ func (*pipelineDatasource) Metadata(ctx context.Context, req datasource.Metadata
 
 func (*pipelineDatasource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: heredoc.Doc(`
+			Use this data source to look up properties on a specific pipeline. This is particularly useful for looking up the webhook URL for each pipeline.
+
+			More info in the Buildkite [documentation](https://buildkite.com/docs/pipelines).
+		`),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The GraphQL ID of the pipeline.",
 			},
 			"name": schema.StringAttribute{
 				Computed:            true,

buildkite/data_source_team.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
@@ -46,10 +47,13 @@ func (t *teamDatasource) Metadata(ctx context.Context, req datasource.MetadataRe
 
 func (t *teamDatasource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "This datasource allows you to get a team from Buildkite.",
+		MarkdownDescription: heredoc.Doc(`
+			Use this data source to retrieve a team by slug or id. You can find out more about teams in the Buildkite
+			[documentation](https://buildkite.com/docs/pipelines/permissions).
+		`),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				MarkdownDescription: "The ID of the team.",
+				MarkdownDescription: "The ID of the team to find. Use either ID or slug.",
 				Optional:            true,
 				Computed:            true,
 				Validators: []validator.String{
@@ -64,7 +68,7 @@ func (t *teamDatasource) Schema(ctx context.Context, req datasource.SchemaReques
 				Computed:            true,
 			},
 			"slug": schema.StringAttribute{
-				MarkdownDescription: "The slug of the team.",
+				MarkdownDescription: "The slug of the team to find. Use either ID or slug.",
 				Computed:            true,
 				Optional:            true,
 			},
@@ -73,7 +77,7 @@ func (t *teamDatasource) Schema(ctx context.Context, req datasource.SchemaReques
 				Computed:            true,
 			},
 			"privacy": schema.StringAttribute{
-				MarkdownDescription: "The privacy of the team.",
+				MarkdownDescription: "The privacy setting of the team.",
 				Computed:            true,
 			},
 			"description": schema.StringAttribute{

buildkite/provider.go

@@ -143,27 +143,30 @@ func (tf *terraformProvider) Resources(context.Context) []func() resource.Resour
 
 func (*terraformProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: `
+		This provider can be used to manage resources on [buildkite.com](https://buildkite.com).
+		`,
 		Attributes: map[string]schema.Attribute{
 			SchemaKeyOrganization: schema.StringAttribute{
-				Optional:    true,
-				Description: "The Buildkite organization slug",
+				Optional:            true,
+				MarkdownDescription: "The Buildkite organization slug. This can be found on the [settings](https://buildkite.com/organizations/~/settings) page. If not provided, the value is taken from the `BUILDKITE_ORGANIZATION_SLUG` environment variable.",
 			},
 			SchemaKeyAPIToken: schema.StringAttribute{
-				Optional:    true,
-				Description: "API token with GraphQL access and `write_pipelines, read_pipelines` and `write_suites` REST API scopes",
-				Sensitive:   true,
+				Optional:            true,
+				MarkdownDescription: "API token with GraphQL access and `write_pipelines`, `read_pipelines` and `write_suites` REST API scopes. You can generate a token from [your settings page](https://buildkite.com/user/api-access-tokens/new?description=terraform&scopes[]=write_pipelines&scopes[]=write_suites&scopes[]=read_pipelines&scopes[]=graphql). If not provided, the value is taken from the `BUILDKITE_API_TOKEN` environment variable.",
+				Sensitive:           true,
 			},
 			SchemaKeyGraphqlURL: schema.StringAttribute{
-				Optional:    true,
-				Description: "Base URL for the GraphQL API to use",
+				Optional:            true,
+				MarkdownDescription: "Base URL for the GraphQL API to use. If not provided, the value is taken from the `BUILDKITE_GRAPHQL_URL` environment variable.",
 			},
 			SchemaKeyRestURL: schema.StringAttribute{
-				Optional:    true,
-				Description: "Base URL for the REST API to use",
+				Optional:            true,
+				MarkdownDescription: "Base URL for the REST API to use. If not provided, the value is taken from the `BUILDKITE_REST_URL` environment variable.",
 			},
 			"archive_pipeline_on_delete": schema.BoolAttribute{
-				Optional:    true,
-				Description: "Archive pipelines when destroying instead of completely deleting.",
+				Optional:            true,
+				MarkdownDescription: "Enable this to archive pipelines when destroying the resource. This is opposed to completely deleting pipelines.",
 			},
 		},
 		Blocks: map[string]schema.Block{

buildkite/resource_agent_token.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 	resource_schema "github.com/hashicorp/terraform-plugin-framework/resource/schema"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
@@ -180,25 +181,33 @@ func (at *AgentTokenResource) Read(ctx context.Context, req resource.ReadRequest
 
 func (AgentTokenResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = resource_schema.Schema{
+		MarkdownDescription: heredoc.Doc(`
+			This resource allows you to create and manage non-clustered agent tokens.
+			You can find out more about clusters in the Buildkite [documentation](https://buildkite.com/docs/agent/v3/tokens).
+		`),
 		Attributes: map[string]resource_schema.Attribute{
 			"description": resource_schema.StringAttribute{
-				Optional: true,
+				Optional:            true,
+				MarkdownDescription: "The description of the agent token. Used to help identify its use.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
 			},
 			"id": resource_schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The GraphQL ID of the agent token.",
 			},
 			"token": resource_schema.StringAttribute{
-				Computed:  true,
-				Sensitive: true,
+				Computed:            true,
+				Sensitive:           true,
+				MarkdownDescription: "The token value used by an agent to register with the API.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"uuid": resource_schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The UUID of the agent token.",
 			},
 		},
 	}

buildkite/resource_cluster.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/hashicorp/terraform-plugin-framework/path"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 	resource_schema "github.com/hashicorp/terraform-plugin-framework/resource/schema"
@@ -44,17 +45,22 @@ func (c *clusterResource) Configure(ctx context.Context, req resource.ConfigureR
 
 func (c *clusterResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = resource_schema.Schema{
-		MarkdownDescription: "A Cluster is a group of Agents that can be used to run your builds. " +
-			"Clusters are useful for grouping Agents by their capabilities, such as operating system, hardware, or location. ",
+		MarkdownDescription: heredoc.Doc(`
+			This resource allows you to create and manage a Buildkite Cluster to run your builds in.
+			Clusters are useful for grouping agents by there capabilities or permissions.
+			Find out more information in our [documentation](https://buildkite.com/docs/clusters/overview).
+		`),
 		Attributes: map[string]resource_schema.Attribute{
 			"id": resource_schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The GraphQL ID of the cluster.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"uuid": resource_schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The UUID of the cluster.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
@@ -64,12 +70,18 @@ func (c *clusterResource) Schema(ctx context.Context, req resource.SchemaRequest
 				Required:            true,
 			},
 			"description": resource_schema.StringAttribute{
-				Optional:            true,
-				MarkdownDescription: "A description for the Cluster. Consider something short but clear on the Cluster's function.",
+				Optional: true,
+				MarkdownDescription: heredoc.Doc(`
+					This is a description for the cluster, this may describe the usage for it, the region, or something else
+					which would help identify the Cluster's purpose.
+				`),
 			},
 			"emoji": resource_schema.StringAttribute{
-				Optional:            true,
-				MarkdownDescription: "An emoji to represent the Cluster. Accepts the format :buildkite:.",
+				Optional: true,
+				MarkdownDescription: heredoc.Doc(`
+					An emoji to use with the Cluster, this can either be set using :buildkite: notation, or with the
+					emoji itself, such as 🚀.
+				`),
 			},
 			"color": resource_schema.StringAttribute{
 				Optional:            true,

buildkite/resource_cluster_agent_token.go

@@ -47,28 +47,32 @@ func (ct *ClusterAgentToken) Schema(_ context.Context, _ resource.SchemaRequest,
 		MarkdownDescription: "A Cluster Agent Token is a token used to connect an agent to a cluster in Buildkite.",
 		Attributes: map[string]resource_schema.Attribute{
 			"id": resource_schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The GraphQL ID of the token.",
 			},
 			"uuid": resource_schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The UUID of the token.",
 			},
 			"description": resource_schema.StringAttribute{
 				Required:            true,
-				MarkdownDescription: "A description about what this cluster agent token is used for",
+				MarkdownDescription: "A description about what this cluster agent token is used for.",
 			},
 			"token": resource_schema.StringAttribute{
-				Computed:  true,
-				Sensitive: true,
+				Computed:            true,
+				Sensitive:           true,
+				MarkdownDescription: "The token value used by an agent to register with the API.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"cluster_id": resource_schema.StringAttribute{
 				Required:            true,
-				MarkdownDescription: "The ID of the Cluster that this Cluster Agent Token belongs to.",
+				MarkdownDescription: "The GraphQL ID of the Cluster that this Cluster Agent Token belongs to.",
 			},
 			"cluster_uuid": resource_schema.StringAttribute{
-				Computed: true,
+				Computed:            true,
+				MarkdownDescription: "The UUID of the Cluster that this token belongs to.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},