Rework defaults definitions and comments

defaults/main.yml

@@ -12,7 +12,7 @@
 
 # .. envvar:: acme_tiny__config_dir
 #
-# Configuration base directory
+# :program:`acme-tiny` configuration base directory.
 acme_tiny__config_dir: '/etc/ssl/acme-tiny'
 
 
@@ -23,63 +23,67 @@ 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). By default this will be set to the (first) domain name defined
+# in :envvar:`acme_tiny__domain`.
 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 bit 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 +133,7 @@ acme_tiny__cert_type: 'plain'
 # User configuration [[[
 # ----------------------
 
-# User account used for running acme-tiny
+# User account meant for running certificate renewal via this Ansible 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,17 @@ acme_tiny__user_group: '{{ acme_tiny__user_name }}'
 # Home directory.
 acme_tiny__user_home: '/var/lib/acme-tiny'
 
-                                                                   # ]]]
-# Renewal setup [[[
-# -----------------
 
-# .. envvar:: acme_tiny__account_key
+# .. envvar:: acme_tiny__log_dir
 #
-# Account key.
-acme_tiny__account_key: 'account.key'
+# Log directory owned by :envvar:`acme_tiny__user_name`.
+acme_tiny__log_dir: '/var/log/acme-tiny'
+
+
+# .. envvar:: acme_tiny__log_file
+#
+# Log file defined in :file:`~/.ansible.cfg` of :envvar:`acme_tiny__user_name`.
+acme_tiny__log_file: '{{ acme_tiny__log_dir }}/{{ acme_tiny__user_name }}.log'
 
                                                                    # ]]]
                                                                    # ]]]

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,14 +38,20 @@ 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
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 When requesting the certificate :program:`acme-tiny` will place a challenge
 file in :file:`/var/www/acme-challenges` which has to be accessible through
 ``http://<fqdn>/.well-known/acme-challenge`` for every domain requested in
-the certificate. Make sure you add a corresponding definition in your Web
-server configuration.
+the certificate. Make sure to point the DNS entry of the domain name
+configured onto the system running this role and to add a corresponding
+definition in your Web server configuration.
+
+The following snippets are meant as an example. Depending on the Web server
+configuration they need to be slightly adjusted.
 
 **Apache 2**
 
@@ -72,6 +83,8 @@ server configuration.
     )
 
 
+.. _acme_tiny_ref_example_playbook:
+
 Example playbook
 ----------------
 
@@ -82,6 +95,8 @@ SSL certificate would looke like this:
    :language: yaml
 
 
+.. _acme_tiny_ref_example_inventory:
+
 Example inventory
 -----------------
 
@@ -92,14 +107,14 @@ to the ``[acme_tiny]`` host group in the Ansible inventory::
     hostname
 
 Obviously, the :doc:`defaults` might not be suitable for everybody. Especially
-the :envvar:`acme_tiny__domain` variable is likely to be defined individually.
-This can be done via host variables in
+the :envvar:`acme_tiny__domain` variable needs to be defined individually.
+This can be done via Ansible host variables in
 :file:`/etc/ansible/host_vars/<hostname>/acme_tiny.yml`.
 
 If there are multiple certificates that should be managed with this Ansible
-role the individual configurations would be defined in separate "domain"
+role, the individual configurations could be defined in separate "domain"
 files (e.g. :file:`/etc/ansible/vars/<domain>.yml`) and then passed with the
-Ansible ``--extra-vars`` argument to the playbook run.
+Ansible ``--extra-vars`` argument to the playbook execution.
 
 ..
  Local Variables:

docs/introduction.rst

@@ -23,9 +23,9 @@ This role requires at least Ansible ``v2.0.0``. To install it, run:
 acme-tiny
 ^^^^^^^^^
 
-As there are different ways to setup ``acme-tiny`` on the various distributions
-this task is not covered by this Ansible role. It has to be done manually
-prior to running the role.
+As there are different ways to setup :program:`acme-tiny` on the various
+distributions this task is not covered by the Ansible role. It has to be done
+manually prior to running the role.
 
 For Gentoo users the role author provides an `acme-tiny ebuild
 <https://github.com/ganto/linuxmonk-overlay/tree/master/app-crypt/acme-tiny>`_