Centralize user documentation

Change-Id: Icf1643f3d6c87a596e6a6b5cdb73dced42ea0797

doc/source/index.rst

@@ -11,7 +11,5 @@ Contents:
    :maxdepth: 1
 
    install/index
-   howto
+   user/index
    contributing
-   troubleshooting
-   vagrant

doc/source/troubleshooting.rst

@@ -1 +0,0 @@
-.. include:: ../../troubleshooting.rst

doc/source/user/howto.rst

@@ -322,10 +322,10 @@ If you wish to include an extra element into the IPA disk image, such as a
 custom hardware manager, you can pass the variable ``ipa_extra_dib_elements``
 as a space-separated list of elements. This defaults to an empty string.
 
-.. include:: deploy/dhcp.rst
+.. include:: dhcp.rst
 
 Use Bifrost with Keystone
 =========================
-.. include:: deploy/keystone.rst
+.. include:: keystone.rst
 
 

doc/source/user/index.rst

@@ -0,0 +1,15 @@
+##################
+Bifrost User Guide
+##################
+
+As bifrost is primarilly intended to be a tool for use by administrators,
+this documentation serves as a blend of both Admin and User documentation.
+
+.. toctree::
+   :maxdepth: 1
+
+   vagrant
+   virsh
+   howto
+   troubleshooting
+

doc/source/user/keystone.rst

@@ -11,10 +11,10 @@ Bifrost execution with Keystone
 ===============================
 
 Ultimately, as bifrost was designed for relatively short-lived
-installations for rapid hardware deployment, the default operating
-mode is referred to as ``noauth`` mode. With that, in order to
-leverage keystone authentication for the roles, one of the
-following steps need to take place.
+installations to facilitate rapid hardware deployment, the default
+operating mode is referred to as ``noauth`` mode. With that,
+in order to leverage keystone authentication for the roles,
+one of the following steps need to take place.
 
 #. Update the role defaults for each role you plan to make use.
    This may not make much sense  for most users, unless they are

doc/source/user/vagrant.rst

@@ -1,19 +1,34 @@
-==============================
-Vagrant support for developers
-==============================
+.. _vagrant:
 
-Bifrost vagrant file for developers can be found in the
-``tools/vagrant_dev_env`` directory. Running ``vagrant up`` from
-within this folder will bring up an Ubuntu Trusty box with Bifrost
+Bifrost via Vagrant
+===================
+
+One of the main user audiences that we've found is for users to utilize
+vagrant in order to build quick development environments, or for their
+environments to facilitate deployments, as the intent is for relatively
+short lived installations.
+
+As such, a virtual machine can be started with vagrant executing the
+following commands::
+
+  cd tools/vagrant_dev_env
+  vagrant up
+
+This will bring up an Ubuntu based virtual machine, with bifrost
 installed.
 
+.. note:: Virtual machine images, as well as all of the software
+          used in bifrost can take some time to install. Typically
+          expect ``vagrant up`` to take at least fifteen minutes if
+          you do not already have the virtual machine image on your
+          machine.
+
 By default, the VM will have three interfaces:
 
 - **eth0** - connected to a NAT network
 - **eth1** - connected to Host-only network named: vboxnet1
 - **eth2** - bridged - adapter must be set in Vagrantfile
 
--------------------------
 Walkthrough done on OS X
 -------------------------
 Setup vagrant by:
@@ -25,7 +40,7 @@ Setup vagrant by:
 
 Configure Vagrant with the correct box::
 
-  vagrant box add ubuntu/trusty64
+  vagrant box add ubuntu/xenial64
 
 Clone bifrost repo::
 
@@ -47,7 +62,6 @@ Boot the VM with::
 
   vagrant up
 
---------------------
 Installation Options
 --------------------
 Ansible is installed within the VM directly from `source

doc/source/user/virsh.rst

@@ -1,10 +1,12 @@
 Deploying with libvirt
 ======================
 
-In order to deploy bifrost with libvirt, but managing baremetal servers, a special
-network config needs to be setup.
+In order to deploy bifrost with libvirt, in order to support managing
+baremetal servers from with-in that libvirt VM, a special network
+configuration is required.
 
 Two networks need to be created:
+
 - default network, that will be a standard virtual network, using NAT.
 - provisioning network, that will be used for PXE boot. As we need to setup
   a dhcp server on bifrost guest, creating a virtual network will give
@@ -14,52 +16,52 @@ Two networks need to be created:
   Please note that you will need to have macvlan enabled on your kernel.
 
 When creating the guest, a minimum of 8GB of memory is needed in order to
-build disk images properly. Also when defining the interfaces for the guest, the two
-networks that have been created need to be attached.
+build disk images along with run the services to support bifrost.
 
-These sample commands will spin up a bifrost vm based on centos:
+When defining the interfaces for the guest, the two networks that have been
+created need to be attached.
 
-virsh net-define --file network/default.xml
-virsh net-start default
-virsh net-define --file network/br_direct.xml
-virsh net-start br_direct
-virsh define --file vm/baremetal.xml
-virsh start baremetal
-virsh console baremetal
+These sample commands will spin up a bifrost vm based on centos::
+
+  virsh net-define --file tools/virsh_dev_env/network/default.xml
+  virsh net-start default
+  virsh net-define --file tools/virsh_dev_env/network/br_direct.xml
+  virsh net-start br_direct
+  virsh define --file tools/virsh_dev_env/vm/baremetal.xml
+  virsh start baremetal
+  virsh console baremetal
 
 When you login into baremetal, the interface for the provisioning
-network will be down. You may need to add an IP manually:
+network will be down. You may need to add an IP manually::
 
-ip addr add <<provisioning_ip_address>>/<<mask>> dev <<interface>>
-ip link set <<interface>> up
+  ip addr add <<provisioning_ip_address>>/<<mask>> dev <<interface>>
+  ip link set <<interface>> up
 
 Where to get guest images
-=========================
+-------------------------
 In order to create the guest VMs, you will need a cloud image
 for the distro you want to deploy. You will need to download the
 guest image on a directory on the host, and then in the template
 for the VM, you can specify it on the disk section, as shown
 in the example template.
 
-Please follow the information on this link to get the images:
-
-http://docs.openstack.org/image-guide/obtain-images.html
+Please see the `OpenStack Image Guide <http://docs.openstack.org/image-guide/obtain-images.html>`_
+for options and locations for obtaining guest images.
 
 Add credentials to guest image
-==============================
+------------------------------
 
 Normally guest images come without user and password, they rely on ssh to
 allow access. In this case, it can be useful to enable ssh access to some
 user from host to guest. A way to do that, is creating a config drive
 and reference it on the template for the guest VM.
 
-A useful script to generate config drives can be found at:
+A useful script to generate config drives can be found
+`here <https://github.com/larsks/virt-utils/blob/master/create-config-drive>`_.
 
-https://github.com/larsks/virt-utils/blob/master/create-config-drive
+Relying on this script, a config drive can be created with::
 
-Relying on this script, a config drive can be created with:
-
-create-config-drive -k ~/.ssh/id_rsa.pub config.iso
+  create-config-drive -k ~/.ssh/id_rsa.pub config.iso
 
 And then this ISO can be referenced on the guest VM template.
 

doc/source/vagrant.rst

@@ -1 +0,0 @@
-.. include:: ../../README.vagrant.rst