reformat documentation to fit terraform registry

Grant Gongaware · Grant Gongaware · commit e9c916a60bf9 · 2020-11-06T09:40:24.000-08:00
diff --git a/docs/guides/cloud_init.md b/docs/guides/cloud_init.md
@@ -3,7 +3,7 @@
 ## Sample file
 
 main.tf:
-```tf
+```hcl
 /* Uses cloud-init options from Proxmox 5.2 */
 resource "proxmox_vm_qemu" "cloudinit-test" {
   name = "tftest1.xyz.com"
diff --git a/docs/guides/installation.md b/docs/guides/installation.md
@@ -1,4 +1,31 @@
-# How to get terraform to recognize third party provider
+
+# Automatic Registry Installation
+
+To install this provider, copy and paste this code into your Terraform configuration (include a version tag). 
+```hcl
+terraform {
+  required_providers {
+    proxmox = {
+      source = "Telmate/proxmox"
+      version = "<version tag>"
+    }
+  }
+}
+
+provider "proxmox" {
+  # Configuration options
+}
+```
+
+Then, run
+```shell
+terraform init
+```
+
+
+# Manual Build & Install
+
+## How to get terraform to recognize third party provider
 
 Third-party plugins (both providers and provisioners) can be manually installed into the user plugins directory,
 located at `%APPDATA%\terraform.d\plugins` on Windows and `~/.terraform.d/plugins` on other systems. Plugins come
@@ -10,14 +37,14 @@ In order to build the required executables, [install Go](https://golang.org/doc/
 repository and run the following commands inside the cloned repository. Since this plugin is both a provider and
 provisioner in one, there are two install commands.
 
-```
+```shell
 go install github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmox
 go install github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provisioner-proxmox
 ```
 
 Then create the executables. They are placed in the `bin` folder inside the repository.
 
-```
+```shell
 make
 ```
 
diff --git a/docs/index.md b/docs/index.md
@@ -1,9 +1,51 @@
-# Documentation: Terraform provider plugin for Proxmox
+# Proxmox Provider
 
-## Table of contents
+A Terraform provider is responsible for understanding API interactions and exposing resources. The Proxmox provider
+uses the Proxmox API. This provider exposes two resources: [proxmox_vm_qemu](docs/resources/vm_qemu.md) and [proxmox_lxc](docs/resources/lxc.md).
 
-1. [Install Terraform plugin](installation.md) 
-1. [Terraform Provider](provider.md) 
-1. [Terraform VM Qemu Resource](resource_vm_qemu.md) 
-1. [Terraform LXC Resource](resource_lxc.md) 
-1. [Cloud Init Guide](cloud_init_guide.md) 
+## Creating the connection
+
+When connecting to the Proxmox API, the provider has to know at least three parameters: the URL, username and password.
+One can supply fields using the provider syntax in Terraform. It is recommended to pass secrets through environment 
+variables.
+
+```bash
+export PM_PASS=password
+```
+
+```hcl
+provider "proxmox" {
+    pm_api_url = "https://proxmox-server01.example.com:8006/api2/json"
+    pm_user = "terraform-user@pve"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported in the provider block:
+
+* `pm_api_url` - (Required; or use environment variable `PM_API_URL`) This is the target Proxmox API endpoint.
+* `pm_user` - (Required; or use environment variable `PM_USER`) The user, maybe required to include @pam.
+* `pm_password` - (Required; sensitive; or use environment variable `PM_PASS`) The password.
+* `pm_otp` - (Optional; or use environment variable `PM_OTP`) The  2FA OTP code.
+* `pm_tls_insecure` - (Optional) Disable TLS verification while connecting.
+* `pm_parallel` - (Optional; defaults to 4) Allowed simultaneous Proxmox processes (e.g. creating resources).
+* `pm_log_enable` - (Optional; defaults to false) Enable debug logging, see the section below for logging details.
+* `pm_log_levels` - (Optional) A map of log sources and levels.
+* `pm_log_file` - (Optional; defaults to "terraform-plugin-proxmox.log") If logging is enabled, the log file the provider will write logs to.
+* `pm_timeout` - (Optional; defaults to 300) Timeout value (seconds) for proxmox API calls.
+
+Additionally, one can set the `PM_OTP_PROMPT` environment variable to prompt for OTP 2FA code (if required).
+
+## Logging
+
+The provider is able to output detailed logs upon request. Note that this feature is intended for development purposes, but could also be used to help investigate bugs. For example: the following code when placed into the provider "proxmox" block will enable loging to the file "terraform-plugin-proxmox.log".  All log sources will default to the "debug" level, and any stdout/stderr from sublibraries (proxmox-api-go) will be silenced (set to non-empty string to enable).
+
+```hcl
+  pm_log_enable = true
+  pm_log_file = "terraform-plugin-proxmox.log"
+  pm_log_levels = {
+    _default = "debug"
+    _capturelog = ""
+  }
+```
diff --git a/docs/provider.md b/docs/provider.md
diff --git a/docs/resource_lxc.md b/docs/resource_lxc.md
diff --git a/docs/resources/lxc.md b/docs/resources/lxc.md
@@ -0,0 +1,28 @@
+# LXC Resource
+
+Resources are the most important element in the Terraform language. Each resource block describes one or more 
+infrastructure objects, such as virtual networks, compute instances, or higher-level components such as DNS records.
+
+This resource manages a Proxmox LXC container.
+
+
+```hcl
+resource "proxmox_lxc" "lxc-test" {
+    features {
+        nesting = true
+    }
+    hostname = "terraform-new-container"
+    network {
+        name = "eth0"
+        bridge = "vmbr0"
+        ip = "dhcp"
+        ip6 = "dhcp"
+    }
+    ostemplate = "shared:vztmpl/centos-7-default_20171212_amd64.tar.xz"
+    password = "rootroot"
+    pool = "terraform"
+    storage = "local-lvm"
+    target_node = "node-01"
+    unprivileged = true
+}
+```
diff --git a/docs/resources/vm_qemu.md b/docs/resources/vm_qemu.md
@@ -1,4 +1,4 @@
-# Terraform VM Qemu Resource
+# VM Qemu Resource
 
 Resources are the most important element in the Terraform language. Each resource block describes one or more 
 infrastructure objects, such as virtual networks, compute instances, or higher-level components such as DNS records.
@@ -13,7 +13,7 @@ base with an ISO, and make the rest of the VM resources depend on that base "tem
 When creating a VM Qemu resource, you create a `proxmox_vm_qemu` resource block. The name and target node of the VM are
 the only required parameters.
 
-```tf
+```hcl
 resource "proxmox_vm_qemu" "resource-name" {
     name = "VM name"
     target_node = "Node to create the VM on"
@@ -25,7 +25,7 @@ resource "proxmox_vm_qemu" "resource-name" {
 With preprovision you can provision a VM directly from the resource block. This provisioning method is therefore ran
 **before** provision blocks. When using preprovision, there are three `os_type` options: `ubuntu`, `centos` or `cloud-init`.
 
-```tf
+```hcl
 resource "proxmox_vm_qemu" "prepprovision-test" {
     ...
     preprovision = true
@@ -39,7 +39,7 @@ There is a pre-provision phase which is used to set a hostname, intialize eth0,
 space. This is done over SSH with the `ssh_forward_ip`, `ssh_user` and `ssh_private_key`. Disk resize is done if the file 
 [/etc/auto_resize_vda.sh](https://github.com/Telmate/terraform-ubuntu-proxmox-iso/blob/master/auto_resize_vda.sh) exists.
 
-```tf
+```hcl
 resource "proxmox_vm_qemu" "prepprovision-test" {
     ...
     preprovision = true
@@ -74,7 +74,7 @@ creating a resource that is using Cloud-Init, there are multi configurations pos
 parameter to create based on [a Cloud-init configuration file](https://cloudinit.readthedocs.io/en/latest/topics/examples.html)
 or use the Proxmox variable `ciuser`, `cipassword`, `ipconfig0`, `ipconfig1`, `searchdomain`, `nameserver` and `sshkeys`.
 
-For more information, see the [Cloud-init guide](cloud_init_guide.md).
+For more information, see the [Cloud-init guide](docs/guides/cloud_init.md).
 
 ## Argument reference
 
