add documentation

README.md

@@ -1,13 +1,30 @@
 ![Release](https://img.shields.io/github/release/bmatcuk/terraform-provider-vagrant.svg?branch=master)
-[![Build Status](https://travis-ci.com/bmatcuk/terraform-provider-vagrant.svg?branch=master)](https://travis-ci.com/bmatcuk/terraform-provider-vagrant)
+[![Build Status](https://github.com/bmatcuk/terraform-provider-vagrant/actions/workflows/release.yml/badge.svg)](https://github.com/bmatcuk/terraform-provider-vagrant/actions/workflows/release.yml)
 [![Go Report Card](https://goreportcard.com/badge/github.com/bmatcuk/terraform-provider-vagrant)](https://goreportcard.com/report/github.com/bmatcuk/terraform-provider-vagrant)
 
 # terraform-provider-vagrant
 A Vagrant provider for terraform.
 
+A note about lippertmarkus/vagrant in the registry: when I originally wrote
+this provider, the terraform registry didn't exist. My terraform needs waned
+and I didn't hear about the registry until some time later. lippertmarkus
+forked my provider and published to the registry as a convenience. Thanks! But,
+it's just an older version of this exact same codebase. So, I recommend you use
+bmatcuk/vagrant to get the latest updates instead.
+
 ## Installation
-Download [the latest release] for your appropriate OS and architecture and
-extract the archive. Then copy the binary to [the terraform plugin directory].
+Add bmatcuk/vagrant to [required_providers]:
+
+```hcl
+terraform {
+  required_providers {
+    vagrant = {
+      source  = "bmatcuk/vagrant"
+      version = "~> 3.0.0"
+    }
+  }
+}
+```
 
 ## Usage
 ```hcl
@@ -96,5 +113,4 @@ env TF_LOG=TRACE terraform apply ...
 
 And, of course, you can always run vagrant on your Vagrantfile directly.
 
-[the latest release]: https://github.com/bmatcuk/terraform-provider-vagrant/releases/latest
-[the terraform plugin directory]: https://www.terraform.io/docs/configuration/providers.html#third-party-plugins
+[required_providers]: https://www.terraform.io/docs/language/providers/requirements.html#requiring-providers

docs/index.md

@@ -0,0 +1,50 @@
+---
+page_title: "Provider: Vagrant"
+description: |-
+  Integrate vagrant into terraform.
+---
+
+# Vagrant Provider
+A Vagrant provider for terraform.
+
+A note about lippertmarkus/vagrant in the registry: when I originally wrote
+this provider, the terraform registry didn't exist. My terraform needs waned
+and I didn't hear about the registry until some time later. lippertmarkus
+forked my provider and published to the registry as a convenience. Thanks! But,
+it's just an older version of this exact same codebase. So, I recommend you use
+bmatcuk/vagrant to get the latest updates instead.
+
+## Installation
+Add bmatcuk/vagrant to [required_providers](https://www.terraform.io/docs/language/providers/requirements.html#requiring-providers):
+
+```terraform
+terraform {
+  required_providers {
+    vagrant = {
+      source  = "bmatcuk/vagrant"
+      version = "~> 3.0.0"
+    }
+  }
+}
+```
+
+## Example Usage
+
+```terraform
+provider "vagrant" {
+  # no config
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+## Debugging
+If terrafrom is failing on the vagrant step, you can get additional output by
+running terraform with logging output enabled. Try something like:
+
+```bash
+env TF_LOG=TRACE terraform apply ...
+```
+
+And, of course, you can always run vagrant on your Vagrantfile directly.

docs/resources/vm.md

@@ -0,0 +1,54 @@
+---
+page_title: "vagrant_vm Resource - terraform-provider-vagrant"
+description: |-
+  Integrate vagrant into terraform.
+---
+
+# vagrant_vm (Resource)
+
+## Forcing an Update
+The easiest way to force an update is to set, or change the value of, some
+environment variable. This will signal to terraform that the vagrant_vm
+resource needs to update.
+
+In the example below, a environment variable, `VAGRANTFILE_HASH`, is set to
+the md5 hash of the Vagrantfile. When the file changes, the hash will change,
+and terraform will ask for an update.
+
+## Example Usage
+
+```terraform
+resource "vagrant_vm" "my_vagrant_vm" {
+  env = {
+    # force terraform to re-run vagrant if the Vagrantfile changes
+    VAGRANTFILE_HASH = "${md5(file("path/to/Vagrantfile"))}",
+  }
+  # see schema for additional options
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- **env** (Map of String) Environment variables to pass to the Vagrantfile.
+- **id** (String) The ID of this resource.
+- **vagrantfile_dir** (String) Path to the directory where the Vagrantfile can be found. Defaults to the current directory.
+
+### Read-Only
+
+- **machine_names** (List of String) Names of the vagrant machines from the Vagrantfile. Names are in the same order as ssh_config.
+- **ssh_config** (List of Object) SSH connection information. (see [below for nested schema](#nestedatt--ssh_config))
+
+<a id="nestedatt--ssh_config"></a>
+### Nested Schema for `ssh_config`
+
+Read-Only:
+
+- **agent** (String)
+- **host** (String)
+- **port** (String)
+- **private_key** (String)
+- **type** (String)
+- **user** (String)

examples/provider/provider.tf

@@ -0,0 +1,3 @@
+provider "vagrant" {
+  # no config
+}

examples/resources/vagrant_vm/resource.tf

@@ -0,0 +1,7 @@
+resource "vagrant_vm" "my_vagrant_vm" {
+  env = {
+    # force terraform to re-run vagrant if the Vagrantfile changes
+    VAGRANTFILE_HASH = "${md5(file("path/to/Vagrantfile"))}",
+  }
+  # see schema for additional options
+}

go.mod

@@ -3,6 +3,7 @@ module github.com/bmatcuk/terraform-provider-vagrant
 require (
 	github.com/bmatcuk/go-vagrant v1.4.2
 	github.com/hashicorp/hcl v0.0.0-20180404174102-ef8a98b0bbce // indirect
+	github.com/hashicorp/terraform-plugin-docs v0.4.0 // indirect
 	github.com/hashicorp/terraform-plugin-sdk v1.0.0
 )