docs: minor fixes with OpenStack-Ansible naming

and fixed problems with url (_' replaced to `_).

for reference.

Change-Id: I5bd81fb9b058cc87b01d778bcea74b9c5f332be2

doc/source/reference/architecture/service-arch.rst

@@ -4,7 +4,7 @@ Service architecture
 Introduction
 ~~~~~~~~~~~~
 
-OpenStack-Ansible has a flexible deployment configuration model that
+OpenStack-Ansible (OSA) has a flexible deployment configuration model that
 can deploy all services in separate machine containers or on designated hosts
 without using containers, and all network traffic either on a single
 network interface or on many network interfaces.
@@ -28,15 +28,16 @@ OpenStack-Ansible deploys the following infrastructure components:
 * RabbitMQ
 
   OpenStack services use RabbitMQ for Advanced Message Queuing Protocol (AMQP).
-  OSA deploys RabbitMQ in a clustered configuration with all
-  queues mirrored between the cluster nodes. Because Telemetry (ceilometer)
-  message queue traffic is quite heavy, for large environments we recommend
-  separating Telemetry notifications into a separate RabbitMQ cluster.
+  OpenStack-Ansible deploys RabbitMQ in a clustered configuration
+  with all queues mirrored between the cluster nodes. Because
+  Telemetry (ceilometer) message queue traffic is quite heavy, for large
+  environments we recommend separating Telemetry notifications
+  into a separate RabbitMQ cluster.
 
 * Memcached
 
   OpenStack services use Memcached for in-memory caching, which accelerates
-  transactions. For example, the OpenStack Identity service (keystone) uses
+  transactions. For example, the OpenStack Identity service (Keystone) uses
   Memcached for caching authentication tokens, which ensures that token
   validation does not have to complete a disk or database transaction every
   time the service is asked to validate a token.
@@ -54,9 +55,10 @@ OpenStack-Ansible deploys the following infrastructure components:
 
 * Load balancer
 
-  At least one load balancer is required for a deployment. OSA
-  provides a deployment of `HAProxy`_, but we recommend using a physical
-  load balancing appliance for production environments.
+  At least one load balancer is required for a deployment.
+  OpenStack-Ansible provides a deployment of `HAProxy`_, but we
+  recommend using a physical load balancing appliance for
+  production environments.
 
 * Utility container
 
@@ -74,14 +76,15 @@ OpenStack-Ansible deploys the following infrastructure components:
   deployed to cache DNS lookups and to handle internal DNS name resolution.
   We recommend using this service for large-scale production environments
   because the deployment will be significantly faster. If this service is not
-  used, OSA modifies ``/etc/hosts`` entries for all hosts in the environment.
+  used, OpenStack-Ansible modifies ``/etc/hosts`` entries for all
+  hosts in the environment.
 
-.. _HAProxy: http://www.haproxy.org/
+.. _HAProxy: https://www.haproxy.org/
 .. _Unbound DNS: https://www.unbound.net/
 
 OpenStack services
 ~~~~~~~~~~~~~~~~~~
 
-OSA is able to deploy a multitude of services.
+OpenStack-Ansible is able to deploy a multitude of services.
 Have a look at the role maturity matrix to know the status of the
 service you want to deploy.

doc/source/reference/configuration/extending-osa.rst

@@ -144,7 +144,7 @@ follows:
 
 The hook variables should be configured in a suitable user_variables
 file. An example calling a playbook from a collection (installed
-using user-collection-requirements.yml) :
+using user-collection-requirements.yml):
 
 .. code-block:: bash
 
@@ -167,7 +167,6 @@ You can override the default path to ``user-ansible-venv-requirements.txt`` file
 with ``USER_ANSIBLE_REQUIREMENTS_FILE`` environment variable before running the
 ``bootstrap-ansible.sh`` script.
 
-
 Defining environment variables for deployment
 ---------------------------------------------
 

doc/source/reference/conventions.rst

@@ -51,4 +51,4 @@ into the ansible roles folder.
 Inventory conventions
 ~~~~~~~~~~~~~~~~~~~~~
 
-Please confer to the inventory section of this reference.
+Please refer to the :dev_docs:`inventory section of this reference <inventory/inventory.html>`.

doc/source/reference/index.rst

@@ -2,7 +2,7 @@
 OpenStack-Ansible Reference
 ===========================
 
-This chapter contains all the extra reference information
+This chapter contains all the additional reference information needed
 to deploy, configure, or upgrade an OpenStack-Ansible cloud.
 
 For information on how to deploy your OpenStack-Ansible cloud, refer to the

doc/source/reference/releases.rst

@@ -4,33 +4,35 @@
 Releases
 ========
 
-What is the OSA release model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-OpenStack-Ansible (OSA) uses the 'cycle-trailing' release model as specified
-in the OpenStack `release model reference_`.
+What is the OpenStack-Ansible release model?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenStack-Ansible uses the 'cycle-trailing' release model as specified
+in the OpenStack `release model reference`_.
 
 .. _release model reference: https://releases.openstack.org/reference/release_models.html
 
 How are release tags decided?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 In order to ensure a common understanding of what release versions mean, we
-use `Semantic Versioning 2.0.0_` for versioning as a basis. The exception to
+use `Semantic Versioning 2.0.0`_ for versioning as a basis. The exception to
 the rule is for milestone releases during a development cycle, where releases
 are tagged ``<MAJOR>.0.0.0b<MILESTONE>`` where ``<MAJOR>`` is the next major
 release number, and ``<MILESTONE>`` is the milestone number.
 
 The OpenStack series names are alphabetical, with each letter matched to a
-number (eg: Austin = 1, Bexar = 2, Newton = 14, Pike = 16, etc). OSA adopted
-the same ``<MAJOR>`` release numbering as the Nova project to match the
-overall OpenStack series version numbering.
+number (e.g., Austin = 1, Bexar = 2, Newton = 14, Pike = 16, etc.).
+OpenStack-Ansible adopted the same ``<MAJOR>`` release numbering
+as the Nova project to match the overall OpenStack series version numbering.
 
 .. _Semantic Versioning 2.0.0: https://semver.org
 
-How frequently does OSA release?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How frequently does OpenStack-Ansible release?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Major releases are done every six months according to the `OpenStack release
-schedule_`. Each major release is consistent with an OpenStack series.
+schedule`_. Each major release is consistent with an OpenStack series.
 
 Minor/patch releases are requested for stable branches on the second and last
 Friday of every month. The releases are typically completed within a few days
@@ -38,19 +40,20 @@ of the request.
 
 .. _OpenStack release schedule: https://releases.openstack.org
 
-What version of OpenStack is deployed by OSA?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+What version of OpenStack is deployed by OpenStack-Ansible?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For each OSA release, the OpenStack version that is deployed is set to a
-specific OpenStack `git SHA-1 hash_` (SHA). These are updated after every
-OSA release. The intent is to ensure that OSA users are able to enjoy an
-updated OpenStack environment with smaller increments of change than the
-typical upstream service releases allow for as they are usually very
-infrequent.
+For each OpenStack-Ansible release, the OpenStack version that is
+deployed is set to a specific OpenStack `git SHA-1 hash`_ (SHA).
+These are updated after every OpenStack-Ansible release.
+The intent is to ensure that OpenStack-Ansible users are able to
+enjoy an updated OpenStack environment with smaller increments of
+change than the typical upstream service releases allow for as they are
+usually very infrequent.
 
-This does mean that a stable OSA deployment will include a version of a
-service (eg: nova-17.0.3dev4) which does not match a tag exactly as you may
-expect (eg: nova-17.0.3).
+This does mean that a stable OpenStack-Ansible deployment will
+include a version of a service (e.g.: nova-17.0.3dev4) which does not
+match a tag exactly as you may expect (e.g.: nova-17.0.3).
 
 If you wish to change the SHA to a specific SHA/tag/branch, or wish to use
 your own fork of an OpenStack service, please see the section titled
@@ -58,15 +61,17 @@ your own fork of an OpenStack service, please see the section titled
 
 .. _git SHA-1 hash: https://git-scm.com/book/en/v2/Git-Internals-Git-Objects
 
-When does a patch to an OSA role get into a release?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When does a patch to an OpenStack-Ansible role get into a release?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For each OSA release, the Ansible roles that form that release are set to a
-specific `git SHA-1 hash_` (SHA). These are updated after every OSA release.
+For each OpenStack-Ansible release, the Ansible roles that form that
+release are set to a specific `git SHA-1 hash`_ (SHA). These are updated
+after every OpenStack-Ansible release.
 
-OSA frequently does pro-active bugfix backports. In order to reduce the risk
-of these backports introducing any destabilization, OSA implements a 'soak'
-period for any patches implemented in the stable branches for roles, but also
+OpenStack-Ansible frequently does proactive bugfix backports.
+In order to reduce the risk of these backports introducing any
+destabilization, OpenStack-Ansible implements a 'soak' period for any
+patches implemented in the stable branches for roles, but also
 provides for circumventing this in exceptional circumstances.
 
 A patch merged into a role is immediately tested by other role tests,
@@ -86,6 +91,6 @@ justification.
 We believe that this approach brings a balance of both reasonable stability,
 while still being able to do pro-active backports.
 
-The only exception to this rule is for the ``master`` branch, which
+The only exception to this process is for the ``master`` branch, which
 intentionally consumes the ``master`` branch from all roles between releases
 so that any changes are immediately integration tested.