Rework defaults definitions and comments

defaults/main.yml

@@ -23,63 +23,66 @@ acme_tiny__config_dir: '/etc/ssl/acme-tiny'
 acme_tiny__challenge_dir: '/var/www/acme-challenges'
 
 
-# .. envvar:: acme_tiny__log_dir
-#
-# Log directory.
-acme_tiny__log_dir: '/var/log/acme-tiny'
-
-
-# .. envvar:: acme_tiny__log_file
-#
-# Log file for renewal process.
-acme_tiny__log_file: '{{ acme_tiny__log_dir }}/{{ acme_tiny__user_name }}.log'
-
-
-# .. envvar:: acme_tiny__private_key_length
+# .. envvar:: acme_tiny__account_key
 #
-# Length of the private key, in case new key is generated
-acme_tiny__key_length: 4096
+# File name of the Let's encrypt account key relative to the
+# :envvar:`acme_tiny__config_dir`. For more information see
+# :ref:`_acme_tiny_ref_account_key`
+acme_tiny__account_key: 'account.key'
 
                                                                    # ]]]
 # Domain configuration [[[
 # ------------------------
 
 # .. envvar:: acme_tiny__domain
 #
-# Domain for which certificate is requested. Can be string or list.
+# Domain for which certificate is requested. Value can be a single domain or
+# a list of domain names (e.g. ``[ 'example.com', 'www.example.com' ]``)
 acme_tiny__domain: 'example.com'
 
 
-# .. envvar:: acme_tiny__file_name
+# .. envvar:: acme_tiny__cert_name
 #
-# File name of key, certificate request and certificate (without ending).
+# File name of key, certificate request and certificate (without file
+# extension).
 acme_tiny__cert_name: '{{ acme_tiny__domain[0]
                           if (acme_tiny__domain is iterable and not acme_tiny__domain is string)
                           else acme_tiny__domain }}'
 
 
 # .. envvar:: acme_tiny__cert_dir
 #
-# Directory name where key, certificate requtest and certificate are stored
+# Directory name where key, certificate request and certificate are stored
 # for this domain.
 acme_tiny__cert_dir: '{{ acme_tiny__config_dir }}/{{ acme_tiny__cert_name }}'
 
 
 # .. envvar:: acme_tiny__private_key
 #
-# Private key used for certificate request. Will be generated if not existant.
+# File name of the RSA key used for generating the certificate request. If key
+# doesn't exist yet, a RSA key of :envvar:`acme_tiny__key_length` bit will be
+# generated under this name.
 acme_tiny__private_key: '{{ acme_tiny__cert_dir }}/{{ acme_tiny__cert_name }}.key'
 
 
+# .. envvar:: acme_tiny__key_length
+#
+# Length in bits of the RSA key
+acme_tiny__key_length: 4096
+
+
 # .. envvar:: acme_tiny__cert_request
 #
-# Certificate request. Will be generated if not existant.
+# File name of the certificate request sent to the Let's Encrypt certificate
+# service. The certificate request will be generated using
+# :envvar:`acme_tiny__domain` if not existent.
 acme_tiny__cert_request: '{{ acme_tiny__cert_dir }}/{{ acme_tiny__cert_name }}.csr'
 
 
 # .. envvar:: acme_tiny__certificate
 #
-# Certificate which will be generated.
+# File name of certificate which will be retrieved from the Let's Encrypt
+# certificate authority.
 acme_tiny__certificate: '{{ acme_tiny__cert_dir }}/{{ acme_tiny__cert_name }}.crt'
 
 
@@ -129,7 +132,8 @@ acme_tiny__cert_type: 'plain'
 # User configuration [[[
 # ----------------------
 
-# User account used for running acme-tiny
+# User account meant for running certificate renewal with the ``acme-tiny``
+# role.
 
 # .. envvar:: acme_tiny__user_name
 #
@@ -139,7 +143,7 @@ acme_tiny__user_name: 'certbot'
 
 # .. envvar:: acme_tiny__user_group
 #
-# Primary group of functional user.
+# Primary group of the functional user.
 acme_tiny__user_group: '{{ acme_tiny__user_name }}'
 
 
@@ -148,14 +152,24 @@ acme_tiny__user_group: '{{ acme_tiny__user_name }}'
 # Home directory.
 acme_tiny__user_home: '/var/lib/acme-tiny'
 
+
+# .. envvar:: acme_tiny__log_dir
+#
+# Log directory.
+acme_tiny__log_dir: '/var/log/acme-tiny'
+
+
+# .. envvar:: acme_tiny__log_file
+#
+# Log file for renewal process.
+acme_tiny__log_file: '{{ acme_tiny__log_dir }}/{{ acme_tiny__user_name }}.log'
+
+
                                                                    # ]]]
 # Renewal setup [[[
 # -----------------
 
-# .. envvar:: acme_tiny__account_key
-#
-# Account key.
-acme_tiny__account_key: 'account.key'
+
 
                                                                    # ]]]
                                                                    # ]]]

docs/getting-started.rst

@@ -18,9 +18,14 @@ There are two "modes" how this role can be run:
   for the service restart. Role has to be run with ``root`` privileges. 
 
 
+.. _acme_tiny_ref_prerequisites:
+
 Prerequisites
 -------------
 
+
+.. _acme_tiny_ref_account_key:
+
 Let's Encrypt Account Key
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -33,6 +38,8 @@ Encrypt key <https://github.com/diafygi/acme-tiny#use-existing-lets-encrypt-key>
 Eventually store the account key in :file:`/etc/ssl/acme-tiny/account.key`.
 
 
+.. _acme_tiny_ref_web_server_config:
+
 Web Server Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -72,6 +79,8 @@ server configuration.
     )
 
 
+.. _acme_tiny_ref_example_playbook:
+
 Example playbook
 ----------------
 
@@ -82,6 +91,8 @@ SSL certificate would looke like this:
    :language: yaml
 
 
+.. _acme_tiny_ref_example_inventory:
+
 Example inventory
 -----------------