Use Sphinx any role to ensure that variables which docs refer to ex…

…ist.

Notice the ``pki_private_groups_resent`` → :any:`pki_private_groups_present` change.

Fixed debops/docs#139 for this role.

CHANGES.rst

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+v0.2.10
+-------
+
+*Unreleased*
+
+- Documentation fixes and improvements. Made variables hyperlinks using the
+  `any` role in Sphinx which also ensures that variables which the
+  documentation refers to actually exist. [ypid]
+
 v0.2.9
 ------
 
@@ -22,7 +31,7 @@ v0.2.8
 - Add support for setting filesystem ACL entries for private directories and
   files. [drybjed]
 
-- Include realms defined in ``pki_default_realms`` in tasks that copy files
+- Include realms defined in :any:`pki_default_realms` in tasks that copy files
   from Ansible Controller depending on an Ansible inventory group. [drybjed]
 
 v0.2.7
@@ -64,7 +73,7 @@ v0.2.5
 *Released: 2016-03-02*
 
 - Don't run :program:`pki-authority` script on Ansible Controller if list of
-  ``pki_authorities`` is not defined. [drybjed]
+  :any:`pki_authorities` is not defined. [drybjed]
 
 v0.2.4
 ------
@@ -201,6 +210,6 @@ v0.1.0
   a separate ``debops.dhparam`` Ansible role. Existing hosts won't be affected.
   [drybjed]
 
-- Expose ``ansible_fqdn`` variable as ``pki_fqdn`` so that it can be overridden
+- Expose ``ansible_fqdn`` variable as :any:`pki_fqdn` so that it can be overridden
   if necessary. [drybjed]
 

defaults/main.yml

@@ -143,7 +143,7 @@ pki_acme_tiny_bin: '/usr/local/lib/pki/acme-tiny'
 # .. envvar:: pki_acme_ca
 #
 # Name of the ACME API endpoint used by the ACME client. The name-URL mapping
-# is done in ``pki_acme_ca_api_map`` dictionary variable.
+# is done in :any:`pki_acme_ca_api_map` dictionary variable.
 pki_acme_ca: 'le-live'
 
 
@@ -249,7 +249,7 @@ pki_private_mode: '0640'
 # Create system group specified here if they don't exist. This can be used to
 # ensure that private directories and files are owned by correct group before the
 # role that creates the group is run by Ansible. See
-# :ref:`pki_private_groups_present` for more details.
+# :ref:`pki__ref_private_groups_present` for more details.
 pki_private_groups_present: []
 
 
@@ -364,6 +364,8 @@ pki_authority_preference: [ 'external', 'acme', 'internal', 'selfsigned' ]
 # .. envvar:: pki_realms
 #
 # List of PKI realms configured on all hosts.
+# Refer to the :ref:`documentation of all options <pki__ref_realms>` for
+# more details.
 pki_realms: []
 
 

docs/acme-integration.rst

@@ -159,35 +159,35 @@ ACME configuration variables
 The ``debops.pki`` role has several default variables which can be used to
 control ACME support. The most important are:
 
-``pki_acme``
+:any:`pki_acme`
   Boolean. When ``True``, support for ACME Certificate Authority will be
   configured for all PKI realms unless disabled on the realm level. By default
   the role checks if a public IP address is available and a default domain is
   configured, otherwise the support is disabled automatically.
 
-``pki_acme_install``
+:any:`pki_acme_install`
   Boolean. Enable or disable installation of :program:`acme-tiny` and configuration of
   ACME support without enabling it for all realms. When this variable is set to
-  ``True`` and ``pki_acme`` is set to ``False``, ACME support can be enabled
+  ``True`` and :any:`pki_acme` is set to ``False``, ACME support can be enabled
   independently in each PKI realm. By default, it is set to the same value as
-  ``pki_acme``.
+  :any:`pki_acme`.
 
-``pki_acme_ca``
+:any:`pki_acme_ca`
   Name of the ACME Certificate Authority API endpoint to use. Dictionary with
-  endpoints is defined in the ``pki_acme_ca_api_map`` variable. By default,
+  endpoints is defined in the :any:`pki_acme_ca_api_map` variable. By default,
   ``le-live`` is used which points to the Let's Encrypt Live CA. For testing
   you can switch the default CA to ``le-staging`` which points to Let's Encrypt
   Staging CA.
 
-``pki_acme_default_subdomains``
+:any:`pki_acme_default_subdomains`
   List of subdomains which will be added to the default ACME domain and all
   other domains configured for ACME certificate by default, can be overridden by
   ``item.acme_subdomains`` parameter. By default, the ``www.`` subdomain will be
   added to each domain configured in the realm. Remember that all subdomains
   need to be correctly configured in the DNS for the Certificate Authority to
   sign the request.
 
-Each PKI realm configured in the ``pki_realms`` or ``pki_*_realms`` variables
+Each PKI realm configured in the :any:`pki_realms` or ``pki_*_realms`` variables
 can have several parameters related to the ACME certificates:
 
 ``item.name``
@@ -205,7 +205,7 @@ can have several parameters related to the ACME certificates:
   List of subdomains that should be added to all of the ACME apex/root domains.
   If you want to create an ACME certificate only with the apex domain, you need
   to use this parameter with ``[]`` value to override
-  ``pki_acme_default_subdomains``.
+  :any:`pki_acme_default_subdomains`.
 
 ``item.acme_subdomains``
   List of subdomains added to each apex (root) domain configured in the ACME

docs/custom-files.rst

@@ -26,7 +26,7 @@ Each element of the file list is a dict with specific parameters:
 
 ``group``
   File group, depending on the file type it will be ``root`` (for public files)
-  or a group specified by the ``pki_private_group`` variable, usually
+  or a group specified by the :any:`pki_private_group` variable, usually
   ``ssl-cert`` (for private files).
 
 ``mode``
@@ -41,14 +41,14 @@ There are multiple list variables which can be used on multiple inventory
 levels:
 
 - all hosts in the inventory:
-  - ``pki_private_files``
-  - ``pki_public_files``
+  - :any:`pki_private_files`
+  - :any:`pki_public_files`
 - hosts in specific inventory group:
-  - ``pki_group_private_files``
-  - ``pki_group_public_files``
+  - :any:`pki_group_private_files`
+  - :any:`pki_group_public_files`
 - specific hosts:
-  - ``pki_host_private_files``
-  - ``pki_host_public_files``
+  - :any:`pki_host_private_files`
+  - :any:`pki_host_public_files`
 
 The private files will be copied before PKI realms are created, so that you can
 provide private keys if you want to. Public files will be copied after PKI

docs/defaults-configuration.rst → docs/defaults-detailed.rst

@@ -1,5 +1,5 @@
-Default variables: configuration
-================================
+Default variable details
+========================
 
 Some of ``debops.pki`` default variables have more extensive configuration than
 simple strings or lists, here you can find documentation and examples for them.
@@ -8,7 +8,7 @@ simple strings or lists, here you can find documentation and examples for them.
    :local:
    :depth: 1
 
-.. _pki_private_groups_present:
+.. _pki__ref_private_groups_present:
 
 pki_private_groups_present
 --------------------------
@@ -49,12 +49,12 @@ Ensure two system groups exist, one with a condition:
      - name: 'group2'
        when: '{{ inventory_hostname in specific_inventory_group }}'
 
-.. _pki_realms:
+.. _pki__ref_realms:
 
 pki_realms
 ----------
 
-The set of ``pki_realms`` lists can be used to define the configuration of PKI
+The set of :any:`pki_realms` lists can be used to define the configuration of PKI
 realms located on remote hosts. Each realm keeps a set of private keys and
 certificates which are signed by the various Certificate Authorities.
 
@@ -88,14 +88,14 @@ List of parameters related to the entire PKI realm:
 ``authority``
   Specify name of the internal Certificate Authority to send the internal
   certificate requests to instead of the default one configured in
-  ``pki_default_authority`` variable. This should be the "normal" name of the
+  :any:`pki_default_authority` variable. This should be the "normal" name of the
   authority, not it's subdomain name.
 
 ``acme``
   Optional, boolean. Enable or disable support for ACME Certificate Authority.
-  Can be used to invert the global ``pki_acme`` setting per PKI realm if
+  Can be used to invert the global :any:`pki_acme` setting per PKI realm if
   needed, but support for ACME needs to be present on the remote host for it to
-  work (see ``pki_acme_install`` variable).
+  work (see :any:`pki_acme_install` variable).
 
 ``internal``
   Optional, boolean. Enable or disable support for internal CA certificates in
@@ -106,7 +106,7 @@ List of parameters related to the entire PKI realm:
   Optional. List of directory names (``external``, ``acme``, ``internal``,
   ``selfsigned``) which determines the order in which the PKI realm looks for
   valid certificates. The first found valid certificate is enabled. If not
-  specified, the order configured in ``pki_authority_preference`` will be used.
+  specified, the order configured in :any:`pki_authority_preference` will be used.
 
 ``library``
   Optional. Specify name of the crypto library used to generate private key and
@@ -121,24 +121,24 @@ List of parameters related to the entire PKI realm:
 ``private_dir_group``
   Optional. System group which will be set as the group of the :file:`private/`
   directory of a given PKI realm. By default, ``ssl-cert``. It needs to exist,
-  and can be created using ``pki_private_groups_resent`` list.
+  and can be created using :any:`pki_private_groups_present` list.
 
 ``private_file_group``
   Optional. System group which will be set as the group of the private keys
   inside of the :file:`private/` directory. It needs to exist, and can be created
-  using ``pki_private_groups_present`` list.
+  using :any:`pki_private_groups_present` list.
 
 ``private_dir_acl_groups``
   Optional. List of groups which should be allowed execute (``X``) permission to
   the ``private/`` realm directory. The access will be granted using filesystem
   ACL table. If not specified, the list defined in
-  ``pki_private_dir_acl_groups`` will be applied.
+  :any:`pki_private_dir_acl_groups` will be applied.
 
 ``private_file_acl_groups``
   Optional. List of groups which should be allowed read (``r``) permission to
   the files in the ``private/`` realm directory. The access will be granted
   using filesystem ACL table. If not specified, the list defined in
-  ``pki_private_file_acl_groups`` will be applied.
+  :any:`pki_private_file_acl_groups` will be applied.
 
 ``dhparam``
   Optional, boolean. Enable or disable support for adding the Diffie-Hellman
@@ -161,16 +161,16 @@ respectively:
 ``default_domain``
   Optional. Change the default domain used by a given PKI realm. If not
   specified, default domain is based on the ``name`` parameter if it has at
-  least 1 dot, or it will be taken from ``pki_default_domain`` variable which
+  least 1 dot, or it will be taken from :any:`pki_default_domain` variable which
   is populated by the ``ansible_domain`` variable.
 
 ``default_subdomains``, ``acme_default_subdomains``
   Optional. List of subdomains added to each domain configured in a given PKI
   realm. A special value ``_wildcard_`` can be used to indicate that a wildcard
   domain should be present in the certificate.
 
-  If not specified, ``pki_default_subdomains`` (for internal CA) and
-  ``pki_acme_default_subdomains`` (for ACME CA) will be used. The PKI
+  If not specified, :any:`pki_default_subdomains` (for internal CA) and
+  :any:`pki_acme_default_subdomains` (for ACME CA) will be used. The PKI
   parameters can be set to empty to override the default variables.
 
 ``subject``, ``acme_subject``

docs/external-certificates.rst

@@ -105,7 +105,7 @@ Because files copied from :file:`by-group/all/` and :file:`by-group/inventory_gr
 directories are not overwritten automatically, you will need to remove the
 corresponding files on remote hosts yourself if you want to update them.
 
-The ``pki_inventory_groups`` default variable is a list of Ansible inventory
+The :any:`pki_inventory_groups` default variable is a list of Ansible inventory
 groups that will have their corresponding directories. You need to specify your
 custom inventory groups in order to have them "active".
 

docs/getting-started.rst

@@ -47,7 +47,7 @@ remote hosts.
 Most of these variables are related to Certificate Authority operation, the
 ones you will likely want to change are:
 
-``pki_ca_domain``
+:any:`pki_ca_domain`
   This is the DNS domain used as a base for the internal Certificate Authority
   Distinguished Names. If you use more than one domain in your environment, you
   should set this variable to your preferred domain on all hosts, through
@@ -57,11 +57,11 @@ ones you will likely want to change are:
   configured with no default domain, or the provider domain might be set up by
   default. Make sure that you check what domain is used by your remote hosts.
 
-``pki_ca_organization``
+:any:`pki_ca_organization`
   This is the organizations name used as a base for the internal
   Certificate Authority Distinguished Names.
 
-``pki_ca_root_dn``, ``pki_ca_domain_dn``, ``pki_ca_service_dn``
+:any:`pki_ca_root_dn`, :any:`pki_ca_domain_dn`, :any:`pki_ca_service_dn`
   These variables define the Distinguished Name or Subject of the Root
   Certificate Authority and Domain Certificate Authority. The value is a list
   of DN entries which define the subject.

docs/index.rst

@@ -13,7 +13,7 @@ Ansible role: debops.pki
    acme-integration
    external-certificates
    defaults
-   defaults-configuration
+   defaults-detailed
    system-ca-certificates
    custom-files
    custom-hooks

docs/system-ca-certificates.rst

@@ -25,12 +25,12 @@ from the system CA store.
 
 By default, Debian hosts automatically trust new Root Certificate Authorities
 added in the ``ca-certificates`` package. To control this, you can use
-``pki_system_ca_certificates_trust_new`` boolean variable. Setting this
+:any:`pki_system_ca_certificates_trust_new` boolean variable. Setting this
 variable to ``True`` will ensure that new Root CA certificates are trusted.
 Setting it to ``False`` will not enable new CA certificates automatically.
 
-You can use ``pki_system_ca_certificates_blacklist`` and
-``pki_system_ca_certificates_whitelist`` list variables to define which
+You can use :any:`pki_system_ca_certificates_blacklist` and
+:any:`pki_system_ca_certificates_whitelist` list variables to define which
 certificates will be excluded/included in the CA store. Each list element is
 a regexp of the certificate file name. If a given file is found in both lists,
 it will be excluded from the certificate store.