Various improvements

certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py

@@ -1,22 +1,20 @@
 """
 The `~certbot_dns_cloudflare.dns_cloudflare` plugin automates the process of
-completing a `dns-01` challenge (`~acme.challenges.DNS01`) using the Cloudflare
-API.
+completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) using the
+Cloudflare API.
 
 
 Named Arguments
 ---------------
 
-======================================  =======  ==============================
-Argument                                Default  Description
-======================================  =======  ==============================
-`--dns-cloudflare-credentials`          None     Cloudflare credentials INI
-                                                 file. (See Credentials_.)
-`--dns-cloudflare-propagation-seconds`  10       The number of seconds to wait
-                                                 for DNS to propagate before
-                                                 asking the ACME server to
-                                                 verify the DNS record.
-======================================  =======  ==============================
+========================================  =====================================
+``--dns-cloudflare-credentials``          Cloudflare credentials_ INI file.
+                                          (Required)
+``--dns-cloudflare-propagation-seconds``  The number of seconds to wait for DNS
+                                          to propagate before asking the ACME
+                                          server to verify the DNS record.
+                                          (Default: 10)
+========================================  =====================================
 
 Credentials
 -----------
@@ -34,16 +32,45 @@ credentials, obtained from your Cloudflare
    dns_cloudflare_api_key = 0123456789abcdef0123456789abcdef01234567
 
 The path to this file can be provided interactively or using the
-`--dns-cloudflare-credentials` command-line argument. Certbot records the path
+``--dns-cloudflare-credentials`` command-line argument. Certbot records the path
 to this file for use during renewal, but does not store the file's contents.
 
 .. caution::
    You should protect these API credentials as you would the password to your
    Cloudflare account. Users who can read this file can use these credentials
    to issue API calls on your behalf. Users who can cause Certbot to run using
-   these credentials can complete a `dns-01` challenge to acquire new
+   these credentials can complete a ``dns-01`` challenge to acquire new
    certificates or revoke existing certificates for associated domains.
 
+Examples
+--------
 
+.. code-block:: bash
+   :caption: To acquire a certificate for ``example.com``
+
+   certbot certonly \\
+     --dns-cloudflare \\
+     --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\
+     -d example.com
+
+.. code-block:: bash
+   :caption: To acquire a single certificate for both ``example.com`` and
+             ``www.example.com``
+
+   certbot certonly \\
+     --dns-cloudflare \\
+     --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\
+     -d example.com \\
+     -d www.example.com
+
+.. code-block:: bash
+   :caption: To acquire a certificate for ``example.com``, waiting 60 seconds
+             for DNS propagation
+
+   certbot certonly \\
+     --dns-cloudflare \\
+     --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\
+     --dns-cloudflare-propagation-seconds 60 \\
+     -d example.com
 
 """