Utilize the full power of the DebOps docs format

* Use global.rst hyperlinks. Ref: debops/docs#155 * Use Sphinx inline syntax: Example: debops/docs#153 * Fixed typos Most of the changes are an automated edit done by [sphinx-inline](https://github.com/ypid/ypid-ansible-common/blob/master/bin/sphinx-inline). PR depends on: debops/docs#191
ypid · Jul 23, 2016 · a356088 · a356088
1 parent 56aa4e8
commit a356088
Show file tree

Hide file tree

Showing 9 changed files with 113 additions and 90 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,11 @@
+## For quick testing.
+## Generated by https://github.com/ypid/ypid-ansible-common/blob/master/bin/sphinx-debops-role-build
+docs/Makefile
+docs/_build/
+docs/conf.py
+docs/defaults.rst
+docs/includes/global.rst
+docs/_static/.gitkeep
+docs/_static/custom.css
+docs/_templates/.gitkeep
+docs/_templates/page.html
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,24 +1,31 @@
 Changelog
 =========
 
+.. include:: includes/all.rst
+
 **debops.hashicorp**
 
-This project adheres to `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`_
+This project adheres to `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`__
 and `human-readable changelog <http://keepachangelog.com/>`_.
 
-The current role maintainer is drybjed.
+The current role maintainer is drybjed_.
 
 
 `debops.hashicorp master`_ - unreleased
 ---------------------------------------
 
 .. _debops.hashicorp master: https://github.com/debops/ansible-hashicorp/compare/v0.1.0...master
 
+Changed
+~~~~~~~
+
+- Utilize the full power of the DebOps_ documentation format using RST
+  hyperlinks and Sphinx inline syntax. [ypid_]
 
 debops.hashicorp v0.1.0 - 2016-07-22
 ------------------------------------
 
 Added
 ~~~~~
 
-- Initial release. [drybjed]
+- Initial release. [drybjed_]
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ The `debops.hashicorp` Ansible role can be used to securely install
 [Consul](https://consul.io/), [Terraform](https://terraform.io/),
 [Vault](https://vaultproject.io/) and others.
 
-The selected applications are downloaded from the hashiCorp release repository,
+The selected applications are downloaded from the HashiCorp release repository,
 authenticated using the HashiCorp OpenPGP key and installed on the system.
 After that, other Ansible roles can be used to configure them as needed.
 

diff --git a/defaults/main.yml b/defaults/main.yml
@@ -6,6 +6,8 @@
 
 # .. contents:: Sections
 #    :local:
+#
+# .. include:: includes/all.rst
 
 
 # APT package management [[[
@@ -41,13 +43,13 @@ hashicorp__user: 'hashicorp'
                                                                    # ]]]
 # .. envvar:: hashicorp__group [[[
 #
-# Name of the primary system group of the HashiCorp account.
+# Name of the primary system group of the HashiCorp_ account.
 hashicorp__group: 'hashicorp'
 
                                                                    # ]]]
 # .. envvar:: hashicorp__home [[[
 #
-# Path to the home directory of the HashiCorp account.
+# Path to the home directory of the HashiCorp_ account.
 hashicorp__home: '{{ (ansible_local.root.home
                       if (ansible_local|d() and ansible_local.root|d() and
                           ansible_local.root.home|d())
@@ -56,31 +58,31 @@ hashicorp__home: '{{ (ansible_local.root.home
                                                                    # ]]]
 # .. envvar:: hashicorp__comment [[[
 #
-# The GECOS string set for the HashiCorp account.
+# The GECOS string set for the HashiCorp_ account.
 hashicorp__comment: 'HashiCorp Application Manager'
 
                                                                    # ]]]
 # .. envvar:: hashicorp__shell [[[
 #
-# The default shell of the HashiCorp account.
+# The default shell of the HashiCorp_ account.
 hashicorp__shell: '/usr/sbin/nologin'
                                                                    # ]]]
                                                                    # ]]]
 # OpenPGP key and keyserver [[[
 # -----------------------------
 
 # See :ref:`hashicorp__ref_security` for details about how the role uses the
-# HashiCorp company OpenPGP keys.
+# HashiCorp_ company OpenPGP keys.
 
 # .. envvar:: hashicorp__gpg_key_id [[[
 #
-# The OpenPGP key fingerprint of the HashiCorp company.
+# The OpenPGP key fingerprint of the HashiCorp_ company.
 hashicorp__gpg_key_id: '91A6E7F85D05C65630BEF18951852D87348FFC4C'
 
                                                                    # ]]]
 # .. envvar:: hashicorp__keyserver [[[
 #
-# URL of the OpenPGP keyserver used to obtain the HashiCorp OpenPGP key.
+# URL of the OpenPGP keyserver used to obtain the HashiCorp_ OpenPGP key.
 hashicorp__keyserver: '{{ ansible_local.core.keyserver
                           if (ansible_local|d() and ansible_local.core|d() and
                               ansible_local.core.keyserver|d())
@@ -92,15 +94,15 @@ hashicorp__keyserver: '{{ ansible_local.core.keyserver
 
 # .. envvar:: hashicorp__applications [[[
 #
-# List of HashiCorp applications that should be installd on a given host.
+# List of HashiCorp_ applications that should be installed on a given host.
 # To find out what applications are supported, check the names of the keys
-# in the ``hashicorp__default_version_map`` dictionary.
+# in the :envvar:`hashicorp__default_version_map` dictionary.
 hashicorp__applications: []
 
                                                                    # ]]]
 # .. envvar:: hashicorp__dependent_applications [[[
 #
-# List of HashiCorp applications that are requested by other Ansible roles
+# List of HashiCorp_ applications that are requested by other Ansible roles
 # using dependent variables.
 hashicorp__dependent_applications: []
                                                                    # ]]]
@@ -110,7 +112,7 @@ hashicorp__dependent_applications: []
 
 # .. envvar:: hashicorp__default_version_map [[[
 #
-# YAML dictionary which maps the HashiCorp application names to their versions.
+# YAML dictionary which maps the HashiCorp_ application names to their versions.
 # This is the main dictionary and shouldn't be modified by the user if
 # possible.
 hashicorp__default_version_map:
@@ -135,15 +137,15 @@ hashicorp__default_version_map:
                                                                    # ]]]
 # .. envvar:: hashicorp__version_map [[[
 #
-# An additional YAML dictionary which defines mapping between HashiCorp
+# An additional YAML dictionary which defines mapping between HashiCorp_
 # applications and their versions. This dictionary should be used to override
 # the default version if necessary.
 hashicorp__version_map: {}
 
                                                                    # ]]]
 # .. envvar:: hashicorp__combined_version_map [[[
 #
-# The YAML dictionary used by the role to lookup specific versions of HashiCorp
+# The YAML dictionary used by the role to lookup specific versions of HashiCorp_
 # applications to install.
 hashicorp__combined_version_map: '{{ hashicorp__default_version_map
                                      | combine(hashicorp__version_map) }}'
@@ -153,7 +155,7 @@ hashicorp__combined_version_map: '{{ hashicorp__default_version_map
 # ----------------------------
 # .. envvar:: hashicorp__default_binary_map [[[
 #
-# Some of the HashiCorp applications use different location or name of binaries
+# Some of the HashiCorp_ applications use different location or name of binaries
 # in their archives. This YAML dictionary is used to override the default
 # binary name(s) to the correct ones when necessary. Paths are relative to the
 # specific archive directory.
@@ -182,7 +184,7 @@ hashicorp__combined_binary_map: '{{ hashicorp__default_binary_map
 
 # .. envvar:: hashicorp__src [[[
 #
-# Base path to the directory with HashiCorp binary archives, their hash
+# Base path to the directory with HashiCorp_ binary archives, their hash
 # signatures and OpenPGP signatures.
 hashicorp__src: '{{ (ansible_local.root.src
                      if (ansible_local|d() and ansible_local.root|d() and
@@ -193,7 +195,7 @@ hashicorp__src: '{{ (ansible_local.root.src
                                                                    # ]]]
 # .. envvar:: hashicorp__lib [[[
 #
-# Base path to the directory where HashiCorp archives are unpacked after
+# Base path to the directory where HashiCorp_ archives are unpacked after
 # verification.
 hashicorp__lib: '{{ (ansible_local.root.lib
                      if (ansible_local|d() and ansible_local.root|d() and
@@ -203,7 +205,7 @@ hashicorp__lib: '{{ (ansible_local.root.lib
                                                                    # ]]]
 # .. envvar:: hashicorp__bin [[[
 #
-# Base path to the directory where HashiCorp application binaries will be
+# Base path to the directory where HashiCorp_ application binaries will be
 # installed by the ``root`` account.
 hashicorp__bin: '{{ (ansible_local.root.bin
                      if (ansible_local|d() and ansible_local.root|d() and
@@ -216,13 +218,13 @@ hashicorp__bin: '{{ (ansible_local.root.bin
 
 # .. envvar:: hashicorp__base_url [[[
 #
-# The base URL of the HashiCorp webserver with application releases.
+# The base URL of the HashiCorp_ webserver with application releases.
 hashicorp__base_url: 'https://releases.hashicorp.com/'
 
                                                                    # ]]]
 # .. envvar:: hashicorp__platform [[[
 #
-# Name of the current OS platform in the format used by the HashiCorp
+# Name of the current OS platform in the format used by the HashiCorp_
 # application archive filenames.
 hashicorp__platform: '{{ ansible_system | lower }}'
 
@@ -236,7 +238,7 @@ hashicorp__architecture: '{{ ansible_architecture }}'
 # .. envvar:: hashicorp__architecture_map [[[
 #
 # YAML dictionary that maps the system architecture as used by Ansible to the
-# architecture names used in the HashiCorp archive filenames.
+# architecture names used in the HashiCorp_ archive filenames.
 hashicorp__architecture_map:
   'x86_64': 'amd64'
   'i386': '386'
@@ -245,7 +247,7 @@ hashicorp__architecture_map:
                                                                    # ]]]
 # .. envvar:: hashicorp__tar_suffix [[[
 #
-# The filename suffix of the HashiCorp application archive.
+# The filename suffix of the HashiCorp_ application archive.
 hashicorp__tar_suffix: '{{ hashicorp__platform + "_"
                            + hashicorp__architecture_map[hashicorp__architecture]
                            + ".zip" }}'
@@ -261,7 +263,7 @@ hashicorp__hash_suffix: 'SHA256SUMS'
 # .. envvar:: hashicorp__sig_suffix [[[
 #
 # The filename suffix of the file which contains OpenPGP signature of the file
-# with SHA256 hashes, signed by the HashiCorp OpenPGP key.
+# with SHA256 hashes, signed by the HashiCorp_ OpenPGP key.
 hashicorp__sig_suffix: '{{ hashicorp__hash_suffix + ".sig" }}'
                                                                    # ]]]
                                                                    # ]]]

diff --git a/docs/ansible-integration.rst b/docs/ansible-integration.rst
@@ -3,42 +3,44 @@
 Ansible integration
 ===================
 
+.. include:: includes/all.rst
+
 .. contents::
    :local:
 
 
 Support for other Ansible roles
 -------------------------------
 
-The ``debops.hashicorp`` Ansible role is designed to be used by other Ansible
+The debops.hashicorp_ Ansible role is designed to be used by other Ansible
 roles as role dependency. By design, the application binaries are installed in
 the specified path and the rest of the service configuration, including service
 process manager configuration, firewall, TCP/UDP port registration in
-``/etc/services``, etc. is left to the user or other Ansible roles.
+:file:`/etc/services`, etc. is left to the user or other Ansible roles.
 
-To faciliate seamless role integration, ``debops.hashicorp`` role provides
+To facilitate seamless role integration, debops.hashicorp_ role provides
 a set of default variables and Ansible local facts that can be used by other
 Ansible roles idempotently. Thus, the modification of the role itself shouldn't
 be needed, and it can should be easily integrated in the different playbooks
-and environmentes.
+and environments.
 
 
 Default variables available to other roles
 ------------------------------------------
 
 You can use these variables in the playbook to influence the operation of the
-``debops.hashicorp`` role from another role:
+debops.hashicorp_ role from another role:
 
-``hashicorp__dependent_packages``
-  List of APT packages which should be installed when the ``debops.hashicorp``
+:envvar:`hashicorp__dependent_packages`
+  List of APT packages which should be installed when the debops.hashicorp_
   role is executed.
 
-``hashicorp__dependent_applications``
-  List of HashiCorp applications which should be installed by the
-  ``debops.hashicorp`` role. For the list of available applications, refer to
-  the ``hashicorp__default_version_map`` variable.
+:envvar:`hashicorp__dependent_applications`
+  List of HashiCorp_ applications which should be installed by the
+  debops.hashicorp_ role. For the list of available applications, refer to
+  the :envvar:`hashicorp__default_version_map` variable.
 
-``hashicorp__consul_webui``
+:envvar:`hashicorp__consul_webui`
   Boolean variable which enables installation of additional files needed to
   serve the Consul Web UI page. The role will remember the Web UI installation
   state to ensure idempotence.
@@ -52,7 +54,7 @@ In a hypothetical ``consul`` Ansible role create a default variable:
 
    consul__hashicorp_application: 'consul'
 
-Next, in the playbook that executes your role, include the ``debops.hashicorp``
+Next, in the playbook that executes your role, include the debops.hashicorp_
 role with your custom variable:
 
 .. code-block:: yaml
@@ -69,9 +71,9 @@ role with your custom variable:
 
        - role: consul
 
-This playbook will then install the ``consul`` application after verification,
+This playbook will then install the Consul_ application after verification,
 and configure it using your own Ansible role. Make sure that you use YAML list
-syntax correctly, otherwise the ``debops.hashicorp`` role will fail due to
+syntax correctly, otherwise the debops.hashicorp_ role will fail due to
 wrong variable type mismatch. To install multiple applications at once, you can
 use a different variant of the variables and playbook.
 
@@ -102,32 +104,32 @@ The playbook:
 Ansible local facts
 -------------------
 
-The ``debops.hashicorp`` role maintains a set of Ansible local facts with
+The debops.hashicorp_ role maintains a set of Ansible local facts with
 information about the installed applications. Other roles can use these facts
 in an idempotent way to prepare their own configuration. These facts are:
 
 ``ansble_local.hashicorp.installed``
   Boolean. If ``True``, the role has been correctly configured.
 
 ``ansible_local.hashicorp.applications``
-  YAML dictionary which specifies all currently installed HashiCorp
+  YAML dictionary which specifies all currently installed HashiCorp_
   applications as keys and their versions as values.
 
 ``ansible_local.hashicorp.bin``
   Path to the directory where binaries are installed, by default
-  ``/usr/local/bin``.
+  :file:`/usr/local/bin`.
 
 ``ansible_local.hashicorp.consul_webui``
   Boolean. If ``True``, the Consul Web UI files have been downloaded and
   installed.
 
 ``ansible_local.hashicorp.consul_webui_path``
-  Path to the Consul Web UI files, by default ``/srv/www/consul/sites/public``.
+  Path to the Consul Web UI files, by default :file:`/srv/www/consul/sites/public`.
 
 Examples
 ~~~~~~~~
 
-Check if specific HashiCorp application is installed on a host:
+Check if specific HashiCorp_ application is installed on a host:
 
 .. code-block:: yaml