Merge pull request #52 from go-gandi/docs

Write documentation

.gitignore

@@ -6,6 +6,7 @@ terraform.tfplan
 .terraform
 crash.log
 dist
+.vscode
 
 website/vendor
 

README.md

@@ -6,15 +6,16 @@ This provider currently doesn't support the Email, Organization or Billing APIs.
 
 ## Requirements
 
--	[Terraform](https://www.terraform.io/downloads.html) >= 0.12.x
--	[Go](https://golang.org/doc/install) >= 1.12
+- [Terraform](https://www.terraform.io/downloads.html) >= 0.12.x
+- [Go](https://golang.org/doc/install) >= 1.12
 
 ## Installation
 
 1. Clone the repository
 1. Enter the repository directory
 1. Build the provider:
-```
+
+```shell
 make
 make install
 ```
@@ -28,7 +29,7 @@ See the [Hashicorp Terraform documentation](https://www.terraform.io/docs/plugin
 This example partly mimics the steps of [the official LiveDNS documentation example](http://doc.livedns.gandi.net/#quick-example), using the parts that have been implemented as Terraform resources.
 Note: sharing_id is optional. It is used e.g. when the API key is registered to a user, where the domain you want to manage is not registered with that user (but the user does have rights on that zone/organization).
 
-```
+```terraform
 terraform {
   required_providers {
     gandi = {
@@ -69,7 +70,7 @@ This example sums up the available resources.
 
 If your zone already exists (which is very likely), you may use it as a data source:
 
-```
+```terraform
 terraform {
   required_providers {
     gandi = {
@@ -106,6 +107,7 @@ This provider is distributed under the terms of the Mozilla Public License versi
 Its main author is not affiliated in any way with Gandi - apart from being a happy customer of their services.
 
 ## Development
+
 If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above).
 
 To compile the provider, run `make`.
@@ -117,9 +119,9 @@ Please see the Go documentation for the most up to date information about using
 
 To add a new dependency `github.com/author/dependency` to your Terraform provider:
 
-```
+```shell
 go get github.com/author/dependency
 go mod tidy
 ```
 
-Then commit the changes to `go.mod` and `go.sum`.
+Then commit the changes to `go.mod` and `go.sum`.

docs/data-sources/domain.md

@@ -0,0 +1,20 @@
+# Data Source: domain
+
+Use this data source to get the ID of a domain for other resources.
+
+## Example Usage
+
+```terraform
+data "gandi_domain" "my_domain" {
+    name = "my.domain"
+}
+```
+
+## Argument Reference
+
+* `name` - (Required) The FQDN of the domain.
+
+## Attribute Reference
+
+* `id` - The ID of the domain.
+* `nameservers` - A list of nameservers for the domain.

docs/data-sources/livedns_domain ns.md

@@ -0,0 +1,20 @@
+# Data Source: livedns_domain_ns
+
+Use this data source to get the nameservers of a domain for other resources.
+
+## Example Usage
+
+```terraform
+data "gandi_livedns_domain_ns" "my_domain" {
+    name = "my.domain"
+}
+```
+
+## Argument Reference
+
+* `name` - (Required) The FQDN of the domain.
+
+## Attribute Reference
+
+* `id` - The ID of the domain.
+* `nameservers` - A list of nameservers for the domain.

docs/data-sources/livedns_domain.md

@@ -0,0 +1,19 @@
+# Data Source: livedns_domain
+
+Use this data source to get the ID of a domain for other resources.
+
+## Example Usage
+
+```terraform
+data "gandi_livedns_domain" "my_domain" {
+    name = "my.domain"
+}
+```
+
+## Argument Reference
+
+* `name` - (Required) The FQDN of the domain.
+
+## Attribute Reference
+
+* `id` - The ID of the domain.

docs/index.md

@@ -0,0 +1,81 @@
+# Gandi Provider
+
+The Gandi provider enables the purchasing and management of domain names through the [Gandi domain registrar](https://gandi.net). It also supports management of DNS hosting through the LiveDNS service.
+
+The provider needs to be configured with the proper credentials before it can be used.
+
+Use the navigation to the left to read about the available resources.
+
+## Example Usage
+
+Terraform 0.13 and later:
+
+```terraform
+terraform {
+  required_providers {
+    gandi = {
+      version = "~> 2.0"
+      source   = "go-gandi/gandi"
+    }
+  }
+}
+
+provider "gandi" {
+  key = "MY_API_KEY"
+}
+
+resource "gandi_domain" "example_com" {
+  name = "example.com"
+  nameservers = ["a.dns.server"]
+}
+```
+
+Terraform 0.12:
+
+```terraform
+provider "gandi" {
+  key = "MY_API_KEY"
+}
+
+resource "gandi_domain" "example_com" {
+  name = "example.com"
+  nameservers = ["a.dns.server"]
+}
+```
+
+## Authentication
+
+The Gandi provider supports a couple of different methods for providing authentication credentials.
+
+You can retrieve your API key by visiting the [Account Management](https://account.gandi.net/en/) screen, going to the `Security` tab and generating your `Production API Key`.
+
+Optionally, you can provide a Sharing ID to specify an organization. If set, the Sharing ID indicates the organization that will pay for any ordered products, and will filter collections.
+
+### Static Credentials
+
+!> Hard-coding credentials into any Terraform configuration is not recommended, and risks leaking secrets should the configuration be committed to public version control.
+
+Usage:
+
+```terraform
+provider "gandi" {
+  key = "MY_API_KEY"
+  sharing_id = "MY_SHARING_ID"
+}
+```
+
+### Environment Variables
+
+You can provide your credentials via the `GANDI_KEY` and `GANDI_SHARING_ID` environment variables, representing the API Key and the Sharing ID, respectively.
+
+```terraform
+provider "gandi" {}
+```
+
+Usage:
+
+```terraform
+$ export GANDI_KEY="MY_API_KEY"
+$ export GANDI_SHARING_ID="MY_SHARING_ID"
+$ terraform plan
+```

docs/resources/domain.md

@@ -0,0 +1,44 @@
+# Resource: domain
+
+The Domain resource enables the creation and management of Domains.
+!> Creating a new Domain will result in your account being charged.
+~> It is not currently possible to delete Domains via the provider.
+
+## Example Usage
+
+```terraform
+resource "gandi_domain" "my_domain" {
+    name = "my.domain"
+    autorenew = "true"
+}
+```
+
+## Argument Reference
+
+* `name` - (Required) The FQDN of the domain.
+* `nameservers` - (Optional) A list of nameservers for the domain.
+* `autorenew` - (Optional) Should the domain autorenew?
+* `admin` - (Required) Nested block listing the admin details for the domain. See below for the structure of the contact detail blocks.
+* `billing` - (Required) Nested block listing the billing details for the domain. See below for the structure of the contact detail blocks.
+* `owner` - (Required) Nested block listing the owner details for the domain. See below for the structure of the contact detail blocks.
+* `tech` - (Required) Nested block listing the admin details for the domain. See below for the structure of the contact detail blocks.
+
+Nested contact detail blocks have the following structure:
+
+* `country` - (Required) The two letter country code for the contact.
+* `email` - (Required) The email address of the contact.
+* `family_name` - (Required) The family name of the contact.
+* `given_name` - (Required) The given name of the contact.
+* `street_addr` - (Required) The street address of the contact.
+* `type` - (Required) The type of contact. Can be one of `person`, `company`, `association` or `public`.
+* `phone` - (Required) The phone number for the contact.
+* `city` - (Required) The city the contact is based in.
+* `organisation` - (Required unless the `type` is `person`) The legal name of the organisation.
+* `zip` - (Required) Postal Code/Zip of the contact.
+* `data_obfuscated` - (Optional) Whether to obfuscate contact details in WHOIS. Defaults to `false`.
+* `mail_obfuscated` - (Optional) Whether to obfuscate contact email in WHOIS. Defaults to `false`.
+* `extra_parameters` - (Optional) Extra parameters, needed for some domain registries.
+
+## Attribute Reference
+
+* `id` - The ID of the resource.

docs/resources/livedns_domain.md

@@ -0,0 +1,22 @@
+# Resource: livedns_domain
+
+The `livedns_domain` resource enables a Domain in the LiveDNS management system. You must enable a domain before adding records to it.
+
+## Example Usage
+
+```terraform
+resource "gandi_livedns_domain" "my_domain" {
+    name = "my.domain"
+    ttl = "3600"
+}
+```
+
+## Argument Reference
+
+* `name` - (Required) The FQDN of the domain.
+* `ttl` - (Required) The default TTL of the domain.
+* `automatic_snapshots` - (Optional) Enable the automatic creation of snapshots when changes are made.
+
+## Attribute Reference
+
+* `id` - The ID of the resource.

docs/resources/livedns_record.md

@@ -0,0 +1,27 @@
+# Resource: livedns_record
+
+The `livedns_record` resource creates a record for a domain in the LiveDNS management system.
+!> You must enable a domain using the `livedns_domain` resource before adding records to it.
+
+## Example Usage
+
+```terraform
+resource "gandi_livedns_record" "www_my_domain" {
+    zone = "my.domain"
+    name = "www"
+    type = "A"
+    values = ["127.0.0.2"]
+}
+```
+
+## Argument Reference
+
+* `zone` - (Required) The FQDN of the domain.
+* `name` - (Required) The name of the record.
+* `type` - (Required) The type of the record. Can be one of "A", "AAAA", "ALIAS", "CAA", "CDS", "CNAME", "DNAME", "DS", "KEY", "LOC", "MX", "NS", "OPENPGPKEY", "PTR", "SPF", "SRV", "SSHFP", "TLSA", "TXT", "WKS".
+* `ttl` - (Required) The TTL of the record.
+* `values` - (Required) A list of the values of the record.
+
+## Attribute Reference
+
+* `id` - The ID of the resource.

gandi/data_domain.go

@@ -17,7 +17,7 @@ func dataSourceDomain() *schema.Resource {
 			"nameservers": {
 				Type:        schema.TypeList,
 				Elem:        &schema.Schema{Type: schema.TypeString},
-				Optional:    true,
+				Computed:    true,
 				Description: "A list of nameservers for the domain",
 			},
 		},