Merge pull request #3 from sebastiaan-dev/task/docs

Update documentation

README.md

@@ -1,6 +1,6 @@
 # Terraform Provider for Bitwarden Secrets
 
-This project builds a Terraform Proivder on top of Bitwardens [Secrets Manager CLI](https://bitwarden.com/help/secrets-manager-cli/). It allows for reading secrets into Data Sources, or managing secrets or projects through Resources.
+This project builds a Terraform Provider on top of Bitwarden [Secrets Manager CLI](https://bitwarden.com/help/secrets-manager-cli/). It allows for reading secrets into Data Sources, or managing secrets or projects through Resources.
 
 ## Requirements
 
@@ -57,14 +57,14 @@ resource "bitwarden-secrets_project" "example_project" {
 }
 
 # Create a Terraform managed secret
-resource "bitwarden-secrets_secret" "example" {
+resource "bitwarden-secrets_secret" "managed_secret" {
     key = "test-terraform"
     value = "hello world!"
     project_id = bitwarden-secrets_project.example_project.id
 }
 
 # Or get a secret directly by using its id
-data "bitwarden-secrets_secret" "vpn" {
+data "bitwarden-secrets_secret" "read_only_secret" {
     id = "Id of the secret"
 }
 ```

docs/index.md

@@ -1,23 +1,53 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "bitwarden-secrets Provider"
-subcategory: ""
+layout: ""
+page_title: "Bitwarden Secrets Provider"
 description: |-
-  
+  Use the Bitwarden provider to read, create, or update logins, secure notes and folders in your Bitwarden Vaults.
 ---
 
-# bitwarden-secrets Provider
-
+# Bitwarden Secrets Provider
 
+This project builds a Terraform Provider on top of Bitwardens [Secrets Manager CLI]. It allows for reading secrets with Data Sources, or managing secrets or projects through Resources. Because the provider makes use of the CLI internally it should be available to the system globally, it is therefore recommended to put the `bws` binary in the system path.
 
 ## Example Usage
 
 ```terraform
+terraform {
+  required_providers {
+    bitwarden-secrets = {
+      source  = "sebastiaan-dev/bitwarden-secrets"
+      version = ">=0.1.2"
+    }
+  }
+}
+
+# Configure the provider
 provider "bitwarden-secrets" {
   access_token = "Access token acquired from Bitwarden"
 }
+
+# Create a project managed by Terraform
+resource "bitwarden-secrets_project" "project" {
+  name = "Terraform-Provider"
+}
+
+# Create a secret managed by Terraform
+resource "bitwarden-secrets_secret" "secret" {
+  key        = "Name of the secret"
+  value      = "Value stored on Bitwarden"
+  project_id = bitwarden-secrets_project.project.id
+}
+
+# Or, read a pre-existing secret
+data "bitwarden-secrets_secret" "read_only_secret" {
+  id = "ID of the secret"
+}
 ```
 
+## Authorization
+
+There are some remarks on the behaviour of read and writing from and to secrets. First, in order to use a Data Source secret from the Bitwarden Secrets Manager the currently active `access-token` should have read permissions for the project associated with the secret. For Resource secrets it should either hold that the secret is a child of a project Resource managed by Terraform, or that the currently active `access-token` has both read and write permissions for the associated project.
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
@@ -28,3 +58,5 @@ provider "bitwarden-secrets" {
 ### Optional
 
 - `server_url` (String) URL of the Bitwarden server.
+
+[Secrets Manager CLI]: https://bitwarden.com/help/secrets-manager-cli/

docs/resources/project.md

@@ -13,6 +13,7 @@ Bitwarden Project
 ## Example Usage
 
 ```terraform
+# Create a project managed by Terraform
 resource "bitwarden-secrets_secret" "example" {
   name = "example"
 }

docs/resources/secret.md

@@ -13,6 +13,7 @@ Bitwarden Secret
 ## Example Usage
 
 ```terraform
+# Create a secret managed by Terraform
 resource "bitwarden-secrets_secret" "example" {
   key        = "example"
   value      = "example"

examples/provider/provider.tf

@@ -1,3 +1,30 @@
+terraform {
+  required_providers {
+    bitwarden-secrets = {
+      source  = "sebastiaan-dev/bitwarden-secrets"
+      version = ">=0.1.2"
+    }
+  }
+}
+
+# Configure the provider
 provider "bitwarden-secrets" {
   access_token = "Access token acquired from Bitwarden"
 }
+
+# Create a project managed by Terraform
+resource "bitwarden-secrets_project" "project" {
+  name = "Terraform-Provider"
+}
+
+# Create a secret managed by Terraform
+resource "bitwarden-secrets_secret" "secret" {
+  key        = "Name of the secret"
+  value      = "Value stored on Bitwarden"
+  project_id = bitwarden-secrets_project.project.id
+}
+
+# Or, read a pre-existing secret
+data "bitwarden-secrets_secret" "read_only_secret" {
+  id = "ID of the secret"
+}

examples/resources/bitwarden-secrets_project/resource.tf

@@ -1,3 +1,4 @@
+# Create a project managed by Terraform
 resource "bitwarden-secrets_secret" "example" {
   name = "example"
 }

examples/resources/bitwarden-secrets_secret/resource.tf

@@ -1,3 +1,4 @@
+# Create a secret managed by Terraform
 resource "bitwarden-secrets_secret" "example" {
   key        = "example"
   value      = "example"

templates/index.md.tmpl

@@ -0,0 +1,22 @@
+---
+layout: ""
+page_title: "Bitwarden Secrets Provider"
+description: |-
+  Use the Bitwarden provider to read, create, or update logins, secure notes and folders in your Bitwarden Vaults.
+---
+
+# Bitwarden Secrets Provider
+
+This project builds a Terraform Provider on top of Bitwardens [Secrets Manager CLI]. It allows for reading secrets with Data Sources, or managing secrets or projects through Resources. Because the provider makes use of the CLI internally it should be available to the system globally, it is therefore recommended to put the `bws` binary in the system path.
+
+## Example Usage
+
+{{tffile "examples/provider/provider.tf"}}
+
+## Authorization
+
+There are some remarks on the behaviour of read and writing from and to secrets. First, in order to use a Data Source secret from the Bitwarden Secrets Manager the currently active `access-token` should have read permissions for the project associated with the secret. For Resource secrets it should either hold that the secret is a child of a project Resource managed by Terraform, or that the currently active `access-token` has both read and write permissions for the associated project.
+
+{{ .SchemaMarkdown | trimspace }}
+
+[Secrets Manager CLI]: https://bitwarden.com/help/secrets-manager-cli/