docs: cleanup install docs

This does a few things to the home page and all-in-one single
machine install guide:

* Uses code blocks for formatting
* Adds the customary "$" to the console blocks in the
  all-in-one single machine install guide
* Instructs to use "sudo su stack" and adds a note about
  "sudo visudo" in the all-in-one single machine doc
* Creates a symbolic link to the sample local.conf and links to
  it from the install guide (note that local.conf might be old
  by now)
* Fixes the .gitignore file to only ignore local.conf in the root
  of the repository, otherwise it would ignore local.conf everywhere
  including the samples and doc/source/assets directories.

Change-Id: I50ae7bd32c4c1caa2ac8551fc54b31dd2dfae568

.gitignore

@@ -28,7 +28,7 @@ files/get-pip.py*
 files/ir-deploy*
 files/ironic-inspector*
 files/etcd*
-local.conf
+^local.conf
 local.sh
 localrc
 proto

doc/source/assets/local.conf

@@ -0,0 +1 @@
+../../../samples/local.conf

doc/source/guides/single-machine.rst

@@ -45,31 +45,37 @@ We need to add a user to install DevStack. (if you created a user during
 install you can skip this step and just give the user sudo privileges
 below)
 
-::
+.. code-block:: console
 
-    useradd -s /bin/bash -d /opt/stack -m stack
+    $ sudo useradd -s /bin/bash -d /opt/stack -m stack
 
 Since this user will be making many changes to your system, it will need
 to have sudo privileges:
 
-::
+.. code-block:: console
 
-    apt-get install sudo -y || yum install -y sudo
-    echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+    $ apt-get install sudo -y || yum install -y sudo
+    $ echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+.. note:: On some systems you may need to use ``sudo visudo``.
 
 From here on you should use the user you created. **Logout** and
-**login** as that user.
+**login** as that user:
+
+.. code-block:: console
+
+    $ sudo su stack && cd ~
 
 Download DevStack
 -----------------
 
 We'll grab the latest version of DevStack via https:
 
-::
+.. code-block:: console
 
-    sudo apt-get install git -y || sudo yum install -y git
-    git clone https://git.openstack.org/openstack-dev/devstack
-    cd devstack
+    $ sudo apt-get install git -y || sudo yum install -y git
+    $ git clone https://git.openstack.org/openstack-dev/devstack
+    $ cd devstack
 
 Run DevStack
 ------------
@@ -97,7 +103,7 @@ do the following:
 
 ``local.conf`` should look something like this:
 
-::
+.. code-block:: ini
 
     [[local|localrc]]
     FLOATING_RANGE=192.168.1.224/27
@@ -109,11 +115,14 @@ do the following:
     RABBIT_PASSWORD=flopsymopsy
     SERVICE_PASSWORD=iheartksl
 
+.. note:: There is a sample :download:`local.conf </assets/local.conf>` file
+    under the *samples* directory in the devstack repository.
+
 Run DevStack:
 
-::
+.. code-block:: console
 
-    ./stack.sh
+    $ ./stack.sh
 
 A seemingly endless stream of activity ensues. When complete you will
 see a summary of ``stack.sh``'s work, including the relevant URLs,

doc/source/index.rst

@@ -55,14 +55,14 @@ are usually fine).
 
 You can quickly create a separate `stack` user to run DevStack with
 
-::
+.. code-block:: console
 
    $ sudo useradd -s /bin/bash -d /opt/stack -m stack
 
 Since this user will be making many changes to your system, it should
 have sudo privileges:
 
-::
+.. code-block:: console
 
     $ echo "stack ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/stack
     $ sudo su - stack
@@ -70,7 +70,7 @@ have sudo privileges:
 Download DevStack
 -----------------
 
-::
+.. code-block:: console
 
    $ git clone https://git.openstack.org/openstack-dev/devstack
    $ cd devstack
@@ -83,7 +83,8 @@ Create a local.conf
 
 Create a ``local.conf`` file with 4 passwords preset at the root of the
 devstack git repo.
-::
+
+.. code-block:: ini
 
    [[local|localrc]]
    ADMIN_PASSWORD=secret
@@ -93,12 +94,15 @@ devstack git repo.
 
 This is the minimum required config to get started with DevStack.
 
+.. note:: There is a sample :download:`local.conf </assets/local.conf>` file
+    under the *samples* directory in the devstack repository.
+
 Start the install
 -----------------
 
-::
+.. code-block:: console
 
-   ./stack.sh
+   $ ./stack.sh
 
 This will take a 15 - 20 minutes, largely depending on the speed of
 your internet connection. Many git trees and packages will be