From 31bdb65720052ee2bba5041f17f566fdc0efbd9a Mon Sep 17 00:00:00 2001 From: Patrick G Date: Wed, 11 Oct 2017 08:33:52 -0400 Subject: [PATCH] Improved consistency of provider documentation (#222) - Fixed indentation - Use same naming scheme for all examples (i.e. all caps for provider, REG prefix for registrar) - Use REG_NONE as registrar when provider does not provide it - Use example.tld for example domain - Use 1.2.3.1/24 IP range for examples - A few spelling fixes --- docs/_providers/activedir.md | 6 +++--- docs/_providers/bind.md | 32 ++++++++++++++++---------------- docs/_providers/cloudflare.md | 20 ++++++++++---------- docs/_providers/digitalocean.md | 8 ++++---- docs/_providers/dnsimple.md | 2 +- docs/_providers/gandi.md | 2 +- docs/_providers/gcloud.md | 2 +- docs/_providers/namecheap.md | 6 +++--- docs/_providers/ns1.md | 3 ++- docs/_providers/route53.md | 4 ++-- docs/_providers/softlayer.md | 18 ++++++++++-------- 11 files changed, 53 insertions(+), 50 deletions(-) diff --git a/docs/_providers/activedir.md b/docs/_providers/activedir.md index 7ccc4f24f..5f0727d12 100644 --- a/docs/_providers/activedir.md +++ b/docs/_providers/activedir.md @@ -52,10 +52,10 @@ Here is a simple dns configuration. dnsconfig.js: {% highlight javascript %} var REG_NONE = NewRegistrar('none', 'NONE') -var DSP_ACTIVEDIRECTORY_DS = NewDnsProvider("activedir", "ACTIVEDIRECTORY_PS"); +var ACTIVEDIRECTORY = NewDnsProvider("activedir", "ACTIVEDIRECTORY_PS"); -D('ds.stackexchange.com', REG_NONE, DnsProvider(DSP_ACTIVEDIRECTORY_DS), - A("api","172.30.20.100") +D('example.tld', REG_NONE, DnsProvider(ACTIVEDIRECTORY), + A("test","1.2.3.4") ) {% endhighlight %} diff --git a/docs/_providers/bind.md b/docs/_providers/bind.md index 896b87dcb..911e94b34 100644 --- a/docs/_providers/bind.md +++ b/docs/_providers/bind.md @@ -15,7 +15,7 @@ In your credentials file (`creds.json`), you can specify a `directory` where the {% highlight javascript %} { - "bind":{ + "bind": { "directory": "myzones" } } @@ -24,21 +24,21 @@ In your credentials file (`creds.json`), you can specify a `directory` where the The BIND provider does not require anything in `creds.json`. It does accept some (optional) metadata via your dns config when you create the provider: {% highlight javascript %} -var bind = NewDnsProvider('bind', 'BIND', { - 'default_soa': { - 'master': 'ns1.mydomain.com.', - 'mbox': 'sysadmin.mydomain.com.', - 'refresh': 3600, - 'retry': 600, - 'expire': 604800, - 'minttl': 1440, - }, - 'default_ns': [ - 'ns1.mydomain.com.', - 'ns2.mydomain.com.', - 'ns3.mydomain.com.', - 'ns4.mydomain.com.' - ] +var BIND = NewDnsProvider('bind', 'BIND', { + 'default_soa': { + 'master': 'ns1.example.tld.', + 'mbox': 'sysadmin.example.tld.', + 'refresh': 3600, + 'retry': 600, + 'expire': 604800, + 'minttl': 1440, + }, + 'default_ns': [ + 'ns1.example.tld.', + 'ns2.example.tld.', + 'ns3.example.tld.', + 'ns4.example.tld.' + ] }) {% endhighlight %} diff --git a/docs/_providers/cloudflare.md b/docs/_providers/cloudflare.md index d04038fb7..b57c5ffd0 100644 --- a/docs/_providers/cloudflare.md +++ b/docs/_providers/cloudflare.md @@ -13,7 +13,7 @@ username and access token: {% highlight json %} { - "cloudflare.com":{ + "cloudflare": { "apikey": "your-cloudflare-api-key", "apiuser": "your-cloudflare-email-address" } @@ -58,9 +58,9 @@ var CF_PROXY_DEFAULT_ON = {'cloudflare_proxy_default': 'on'}; The following example shows how to set meta variables with and without aliases: {% highlight json %} -D('example.tld', REG_NAMECOM, DnsProvider(CFLARE), - A('www1','1.2.3.11', CF_PROXY_ON), // turn proxy ON. - A('www2','1.2.3.12', CF_PROXY_OFF), // default is OFF, this is a no-op. +D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE), + A('www1','1.2.3.11', CF_PROXY_ON), // turn proxy ON. + A('www2','1.2.3.12', CF_PROXY_OFF), // default is OFF, this is a no-op. A('www3','1.2.3.13', {'cloudflare_proxy': 'on'}) // why would anyone do this? ); {% endhighlight %} @@ -70,11 +70,11 @@ D('example.tld', REG_NAMECOM, DnsProvider(CFLARE), Example javascript: {% highlight js %} -var REG_NAMECOM = NewRegistrar('name.com','NAMEDOTCOM'); -var CFLARE = NewDnsProvider('cloudflare.com','CLOUDFLAREAPI'); +var REG_NONE = NewRegistrar('none', 'NONE') +var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI'); // Example domain where the CF proxy abides by the default (off). -D('example.tld', REG_NAMECOM, DnsProvider(CFLARE), +D('example.tld', REG_NONE, DnsProvider(CLOUDFLARE), A('proxied','1.2.3.4', CF_PROXY_ON), A('notproxied','1.2.3.5'), A('another','1.2.3.6', CF_PROXY_ON), @@ -83,7 +83,7 @@ D('example.tld', REG_NAMECOM, DnsProvider(CFLARE), ); // Example domain where the CF proxy default is set to "on": -D('example2.tld', REG_NAMECOM, DnsProvider(CFLARE), +D('example2.tld', REG_NONE, DnsProvider(CLOUDFLARE), CF_PROXY_DEFAULT_ON, // Enable CF proxy for all items unless otherwise noted. A('proxied','1.2.3.4'), A('notproxied','1.2.3.5', CF_PROXY_OFF), @@ -111,9 +111,9 @@ The cloudflare provider can manage Page-Rule based redirects for your domains. S // chiphacker.com is an alias for electronics.stackexchange.com -var CFLARE = NewDnsProvider('cloudflare.com','CLOUDFLAREAPI', {"manage_redirects": true}); // enable manage_redirects +var CLOUDFLARE = NewDnsProvider('cloudflare','CLOUDFLAREAPI', {"manage_redirects": true}); // enable manage_redirects -D("chiphacker.com", REG_NAMECOM, DnsProvider(CFLARE), +D("chiphacker.com", REG_NONE, DnsProvider(CLOUDFLARE), // must have A records with orange cloud on. Otherwise page rule will never run. A("@","1.2.3.4", CF_PROXY_ON), A("www", "1.2.3.4", CF_PROXY_ON) diff --git a/docs/_providers/digitalocean.md b/docs/_providers/digitalocean.md index 7c7e6ffba..ca7d06c7c 100644 --- a/docs/_providers/digitalocean.md +++ b/docs/_providers/digitalocean.md @@ -13,7 +13,7 @@ In your providers config json file you must provide your {% highlight json %} { - "digitalocean":{ + "digitalocean": { "token": "your-digitalocean-ouath-token" } } @@ -28,10 +28,10 @@ This provider does not recognize any special metadata fields unique to route 53. Example javascript: {% highlight js %} -var REG_NAMECOM = NewRegistrar("name.com","NAMEDOTCOM"); -var DO = NewDnsProvider("do", "DIGITALOCEAN"); +var REG_NONE = NewRegistrar('none', 'NONE') +var DIGITALOCEAN = NewDnsProvider("do", "DIGITALOCEAN"); -D("example.tld", REG_NAMECOM, DnsProvider(DO), +D("example.tld", REG_NONE, DnsProvider(DIGITALOCEAN), A("test","1.2.3.4") ); {%endhighlight%} diff --git a/docs/_providers/dnsimple.md b/docs/_providers/dnsimple.md index 8ff7ed2cc..4d1eb3c41 100644 --- a/docs/_providers/dnsimple.md +++ b/docs/_providers/dnsimple.md @@ -11,7 +11,7 @@ In your providers config json file you must provide a DNSimple account access to {% highlight json %} { - "dnsimple":{ + "dnsimple": { "token": "your-dnsimple-account-access-token" } } diff --git a/docs/_providers/gandi.md b/docs/_providers/gandi.md index ef564b99c..bfcb23f75 100644 --- a/docs/_providers/gandi.md +++ b/docs/_providers/gandi.md @@ -14,7 +14,7 @@ In your providers config json file you must provide your Gandi.net api key: {% highlight json %} { - "gandi":{ + "gandi": { "apikey": "your-gandi-key" } } diff --git a/docs/_providers/gcloud.md b/docs/_providers/gcloud.md index a71f7d4d5..0b4b2943c 100644 --- a/docs/_providers/gcloud.md +++ b/docs/_providers/gcloud.md @@ -12,7 +12,7 @@ jsId: GCLOUD For Google cloud authentication, DNSControl requires a JSON 'Service Account Key' for your project. Copy the full JSON object into your `creds.json` like so: {% highlight json %} { - "gcloud":{ + "gcloud": { "type": "service_account", "project_id": "mydnsproject", "private_key_id": "a05483aa208364c56716b384efff33c0574d365b", diff --git a/docs/_providers/namecheap.md b/docs/_providers/namecheap.md index fb154e27f..67ba577fd 100644 --- a/docs/_providers/namecheap.md +++ b/docs/_providers/namecheap.md @@ -15,7 +15,7 @@ username and key: {% highlight json %} { - "namecheap.com":{ + "namecheap":{ "apikey": "yourApiKeyFromNameCheap", "apiuser": "yourUsername" } @@ -48,10 +48,10 @@ Namecheap. Example javascript: {% highlight js %} -var namecheap = NewRegistrar("namecheap.com","NAMECHEAP"); +var REG_NAMECHEAP = NewRegistrar("namecheap","NAMECHEAP"); var R53 = NewDnsProvider("r53", "ROUTE53"); -D("example.tld", namecheap, DnsProvider(R53), +D("example.tld", REG_NAMECHEAP, DnsProvider(R53), A("test","1.2.3.4") ); {%endhighlight%} diff --git a/docs/_providers/ns1.md b/docs/_providers/ns1.md index 71c862fd4..40bd9fb78 100644 --- a/docs/_providers/ns1.md +++ b/docs/_providers/ns1.md @@ -29,9 +29,10 @@ This provider does not recognize any special metadata fields unique to ns1. Example javascript: {% highlight js %} +var REG_NONE = NewRegistrar('none', 'NONE') var NS1 = NewDnsProvider("ns1", "NS1"); -D("example.tld", MY_REGISTRAR, DnsProvider(NS1), +D("example.tld", REG_NONE, DnsProvider(NS1), A("test","1.2.3.4") ); {% endhighlight %} diff --git a/docs/_providers/route53.md b/docs/_providers/route53.md index ea19e31f1..2b54d7735 100644 --- a/docs/_providers/route53.md +++ b/docs/_providers/route53.md @@ -33,10 +33,10 @@ This provider does not recognize any special metadata fields unique to route 53. Example javascript: {% highlight js %} -var REG_NAMECOM = NewRegistrar("name.com","NAMEDOTCOM"); +var REG_NONE = NewRegistrar("none","NONE"); var R53 = NewDnsProvider("r53", "ROUTE53"); -D("example.tld", REG_NAMECOM, DnsProvider(R53), +D("example.tld", REG_NONE, DnsProvider(R53), A("test","1.2.3.4") ); {%endhighlight%} diff --git a/docs/_providers/softlayer.md b/docs/_providers/softlayer.md index 6a136c869..2eb041639 100644 --- a/docs/_providers/softlayer.md +++ b/docs/_providers/softlayer.md @@ -13,10 +13,12 @@ To authenticate with SoftLayer requires at least a `username` and `api_key` for It can also optionally take a `timeout` and `endpoint_url` parameter however these are optional and will use standard defaults if not provided. These can be supplied via the standard 'creds.json' like so: {% highlight json %} - "softlayer": { - "username": "myusername", - "api_key": "mysecretapikey" - } +{ + "softlayer": { + "username": "myusername", + "api_key": "mysecretapikey" + } +} {% endhighlight %} To maintain compatibility with existing softlayer CLI services these can also be provided by the `SL_USERNAME` and `SL_API_KEY` environment variables or specified in the ~/.softlayer. @@ -27,10 +29,10 @@ More information about these methods can be found at [the softlayer-go library d Use this provider like any other DNS Provider: {% highlight js %} -var registrar = NewRegistrar("none","NONE"); // no registrar -var softlayer = NewDnsProvider("softlayer", "SOFTLAYER"); +var REG_NONE = NewRegistrar("none","NONE"); // no registrar +var SOFTLAYER = NewDnsProvider("softlayer", "SOFTLAYER"); -D("example.tld", registrary, DnsProvider(softlayer), +D("example.tld", registrary, DnsProvider(SOFTLAYER), A("test","1.2.3.4") ); {%endhighlight%} @@ -41,7 +43,7 @@ This provider does not recognize any special metadata fields unique to SoftLayer For compatibility with the pre-generated NAMESERVER fields it's recommended to set the NS TTL to 86400 such as: {% highlight js %} -D("example.tld", registrary, DnsProvider(softlayer), +D("example.tld", REG_NONE, DnsProvider(SOFTLAYER), {"ns_ttl": "86400"}, A("test","1.2.3.4")