From f561eebf98f2f79a4be34821680231f4c52819aa Mon Sep 17 00:00:00 2001
From: Marcus Weiner <marcus.weiner@gmail.com>
Date: Sat, 20 Jul 2024 21:09:21 +0200
Subject: [PATCH] Improve generated docs

---
 docs/index.md                                            | 8 ++++++--
 examples/data-sources/scaffolding_example/data-source.tf | 3 ---
 examples/provider/provider.tf                            | 3 ++-
 examples/resources/scaffolding_example/resource.tf       | 3 ---
 internal/provider/provider.go                            | 7 +++++++
 internal/provider/provider.md                            | 3 +++
 6 files changed, 18 insertions(+), 9 deletions(-)
 delete mode 100644 examples/data-sources/scaffolding_example/data-source.tf
 delete mode 100644 examples/resources/scaffolding_example/resource.tf
 create mode 100644 internal/provider/provider.md

diff --git a/docs/index.md b/docs/index.md
index d159187..1964344 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,18 +3,22 @@
 page_title: "netboxbgp Provider"
 subcategory: ""
 description: |-
-  
+  This provider allows managing BGP resources in Netbox, when the Netbox BGP plugin https://github.com/netbox-community/netbox-bgp is installed.
+  The provider is intentionally using a similar structure to the e-breuninger/netbox https://registry.terraform.io/providers/e-breuninger/netbox/latest provider. If you're already using that provider, this provider should work smoothly alongside it.
 ---
 
 # netboxbgp Provider
 
+This provider allows managing BGP resources in Netbox, when the [Netbox BGP plugin](https://github.com/netbox-community/netbox-bgp) is installed.
 
+The provider is intentionally using a similar structure to the [`e-breuninger/netbox`](https://registry.terraform.io/providers/e-breuninger/netbox/latest) provider. If you're already using that provider, this provider should work smoothly alongside it.
 
 ## Example Usage
 
 ```terraform
 provider "netboxbgp" {
-  # example configuration here
+  server_url = "https://netbox.my-company.net"
+  api_token  = var.netbox_api_token
 }
 ```
 
diff --git a/examples/data-sources/scaffolding_example/data-source.tf b/examples/data-sources/scaffolding_example/data-source.tf
deleted file mode 100644
index a852489..0000000
--- a/examples/data-sources/scaffolding_example/data-source.tf
+++ /dev/null
@@ -1,3 +0,0 @@
-data "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}
diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf
index c0ce4c8..c690ae3 100644
--- a/examples/provider/provider.tf
+++ b/examples/provider/provider.tf
@@ -1,3 +1,4 @@
 provider "netboxbgp" {
-  # example configuration here
+  server_url = "https://netbox.my-company.net"
+  api_token  = var.netbox_api_token
 }
diff --git a/examples/resources/scaffolding_example/resource.tf b/examples/resources/scaffolding_example/resource.tf
deleted file mode 100644
index 9ae3f57..0000000
--- a/examples/resources/scaffolding_example/resource.tf
+++ /dev/null
@@ -1,3 +0,0 @@
-resource "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}
diff --git a/internal/provider/provider.go b/internal/provider/provider.go
index 883b583..c1c4eeb 100644
--- a/internal/provider/provider.go
+++ b/internal/provider/provider.go
@@ -6,6 +6,7 @@ package provider
 import (
 	"context"
 	"crypto/tls"
+	_ "embed"
 	"net/http"
 
 	"github.com/ffddorf/terraform-provider-netbox-bgp/client"
@@ -20,6 +21,11 @@ import (
 // Ensure NetboxBGPProvider satisfies various provider interfaces.
 var _ provider.Provider = &NetboxBGPProvider{}
 
+var (
+	//go:embed provider.md
+	providerDocs string
+)
+
 // NetboxBGPProvider defines the provider implementation.
 type NetboxBGPProvider struct {
 	// version is set to the provider version on release, "dev" when the
@@ -51,6 +57,7 @@ func (p *NetboxBGPProvider) Metadata(ctx context.Context, req provider.MetadataR
 
 func (p *NetboxBGPProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: providerDocs,
 		Attributes: map[string]schema.Attribute{
 			"server_url": schema.StringAttribute{
 				MarkdownDescription: "Location of Netbox server including scheme (http or https) and optional port. Can be set via the `NETBOX_SERVER_URL` environment variable.",
diff --git a/internal/provider/provider.md b/internal/provider/provider.md
new file mode 100644
index 0000000..d7fa345
--- /dev/null
+++ b/internal/provider/provider.md
@@ -0,0 +1,3 @@
+This provider allows managing BGP resources in Netbox, when the [Netbox BGP plugin](https://github.com/netbox-community/netbox-bgp) is installed.
+
+The provider is intentionally using a similar structure to the [`e-breuninger/netbox`](https://registry.terraform.io/providers/e-breuninger/netbox/latest) provider. If you're already using that provider, this provider should work smoothly alongside it.