Address doc review comments

doc/source/architecture.rst

@@ -26,12 +26,12 @@ Tenks has a concept of 'physical network' which currently must map one-to-one
 to the hardware networks plugged into the hypervisors. It requires device
 mappings to be specified on a hypervisor for each physical network that is to
 be connected to nodes on that hypervisor. This device can be an interface, a
-Linux bridge or an Open vSwitch bridge. For each physical network that is give
+Linux bridge or an Open vSwitch bridge. For each physical network that is given
 a mapping on a hypervisor, a new Tenks-managed Open vSwitch bridge is created.
 If the device mapped to this physnet is an interface, it is plugged directly
 into the new bridge. If the device is an existing Linux bridge, a veth pair is
 created to connect the existing bridge to the new bridge. If the device is an
-existing Open vSwitch bridge, an Open vSwitch patch port is created to link th
+existing Open vSwitch bridge, an Open vSwitch patch port is created to link the
 two bridges.
 
 A new veth pair is created for each physical network that each node on each

doc/source/configuration.rst

@@ -23,11 +23,11 @@ setup on the host where the ``ansible-playbook`` command is executed
 Variable Configuration
 ----------------------
 
-An override file should be created to configure Tenks. Any variables specified
-in this file will take precedence over their default settings in Tenks. This
-will allow you to set options as necessary for your setup, without needing to
-directly modify Tenks' variable files. An example override file can be found
-in ``ansible/override.yml.example``.
+A variable override file should be created to configure Tenks. Any variables
+specified in this file will take precedence over their default settings in
+Tenks. This will allow you to set options as necessary for your setup, without
+needing to directly modify Tenks' variable files. An example override file can
+be found in ``ansible/override.yml.example``.
 
 Most of the configuration you will need to do relates to variables defined in
 ``ansible/host_vars/localhost``. You can set your own values for these in your
@@ -37,14 +37,14 @@ define the types of node you'd like to be able to manage as a dict in
 Format and guidance for available options will be found within the variable
 file.
 
-Broadly, most variables in ``ansible/group_vars/*`` have sensible defaults which
-may be left as-is unless you have a particular need to configure them. A
+Broadly, most variables in ``ansible/group_vars/*`` have sensible defaults
+which may be left as-is unless you have a particular need to configure them. A
 notable exception to this is the variable ``physnet_mappings`` in
 ``ansible/group_vars/hypervisors``, which should map physical network names to
 the device to use for that network: this can be a network interface, or an
 existing OVS or Linux bridge. If these mappings are the same for all hosts in
-your ``hypervisors`` group, you may set a single dict ``physnet_mappings`` in your
-overrides file, and this will be used for all hosts. If different mappings are
-required for different hosts, you will need to individually specify them: for a
-host with hostname *myhost*, set ``physnet_mappings`` within the file
-``ansible/host_vars/myhost``.
+your ``hypervisors`` group, you may set a single dict ``physnet_mappings`` in
+your overrides file, and this will be used for all hosts. If different mappings
+are required for different hosts, you will need to individually specify them in
+an inventory host_vars file: for a host with hostname *myhost*, set
+``physnet_mappings`` within the file ``ansible/inventory/host_vars/myhost``.

doc/source/index.rst

@@ -12,9 +12,9 @@ testing purposes.
 .. toctree::
    :maxdepth: 2
 
-   architecture
    configuration
-   development
    install
-   limitations
    run
+   architecture
+   development
+   limitations

doc/source/install.rst

@@ -1,8 +1,48 @@
+.. _installation:
+
 Installation
-===============
+============
+
+Pre-Requisites
+--------------
+
+Currently, Tenks supports CentOS 7.5.
+
+To avoid conflicts with Python packages installed by the system package manager
+it is recommended to install Tenks in a virtualenv. Ensure that the
+``virtualenv`` Python module is available. For cloning and working with the
+Tenks source code repository, Git is required. These pre-requisites can be
+installed with a command such as::
+
+ $ yum install --assumeyes python-virtualenv git
+
+Tenks Installation
+------------------
+
+Create a virtualenv for Tenks. For example::
+
+ $ virtualenv tenks
+
+Activate the virtualenv and update pip::
+
+ $ source tenks/bin/activate
+ (tenks) $ pip install --upgrade pip
+
+Obtain the Tenks source code and change into the directory. For example::
+
+  (tenks) $ git clone https://github.com/stackhpc/tenks.git
+  (tenks) $ cd tenks
 
 Tenks has dependencies on Ansible roles that are hosted by Ansible Galaxy.
-Given that your virtualenv of choice is active and Ansible (>=2.6) is
-installed inside it, Tenks' role dependencies can be installed by
-``ansible-galaxy install --role-file=requirements.yml
---roles-path=ansible/roles/``.
+These can be installed by a command such as::
+
+  (tenks) $ ansible-galaxy install --role-file=requirements.yml --roles-path=ansible/roles/
+
+Install Tenks and its requirements using the source code checkout::
+
+  (tenks) $ pip install .
+
+If you now wish to run Tenks (see :ref:`run`), keep your virtualenv active. If
+not, deactivate it::
+
+  (tenks) $ deactivate

doc/source/run.rst

@@ -1,3 +1,5 @@
+.. _run:
+
 Running Tenks
 =============
 
@@ -16,21 +18,29 @@ possible values it can take are:
 Execution
 ---------
 
-Currently, Tenks does not have a CLI or wrapper. Deployment can be run by
-calling ``ansible-playbook --inventory ansible/inventory ansible/deploy.yml
---extra-vars=@override.yml``, where ``override.yml`` is the path to your
-override file.
+Currently, Tenks does not have a CLI or wrapper. Before running any of the
+``ansible-playbook`` commands in this section, ensure that your Tenks
+virtualenv is active (see :ref:`installation`). In this section,
+``override.yml`` represents the path to your override file (see
+:ref:`configuration`).
+
+The ``deploy.yml`` playbook will run deployment from start to finish. This can
+be run by calling::
+
+  (tenks) $ ansible-playbook --inventory ansible/inventory ansible/deploy.yml --extra-vars=@override.yml
 
-The ``deploy.yml`` playbook will run deployment from start to finish;
 ``teardown.yml`` is ``deploy.yml``'s "mirror image" to tear down a cluster.
-These playbooks automatically set ``cmd`` appropriately, and they contain
-various constituent playbooks which perform different parts of the deployment.
-An individual section of Tenks can be run separately by substituting
-``ansible/deploy.yml`` in the command above with the path to the playbook(s)
-you want to run. The current playbooks can be seen in the Ansible structure
-diagram in :ref:`architecture`. Bear in mind that you will have to set
-``cmd`` in your override file if you are running any of the sub-playbooks
-individually.
+This can be run by calling::
+
+  (tenks) $ ansible-playbook --inventory ansible/inventory ansible/teardown.yml --extra-vars=@override.yml
+
+``deploy.yml`` and ``teardown.yml`` automatically set ``cmd`` appropriately,
+and they contain various constituent playbooks which perform different parts of
+the deployment.  An individual section of Tenks can be run separately by
+substituting the path to the playbook(s) you want to run into one of the
+commands above.  The current playbooks can be seen in the Ansible structure
+diagram in :ref:`architecture`. Bear in mind that you will have to set ``cmd``
+in your override file if you are running any of the sub-playbooks individually.
 
 Once a cluster has been deployed, it can be reconfigured by modifying the Tenks
 configuration and rerunning ``deploy.yml``. Node specs can be changed