diff --git a/.gitignore b/.gitignore
index e5e1f6aba0..956e13e21c 100644
--- a/.gitignore
+++ b/.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
diff --git a/doc/source/assets/local.conf b/doc/source/assets/local.conf
new file mode 120000
index 0000000000..cfc2a4e9d8
--- /dev/null
+++ b/doc/source/assets/local.conf
@@ -0,0 +1 @@
+../../../samples/local.conf
\ No newline at end of file
diff --git a/doc/source/guides/single-machine.rst b/doc/source/guides/single-machine.rst
index 515ea9a9ee..168172c630 100644
--- a/doc/source/guides/single-machine.rst
+++ b/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,
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fcf1e82d34..6c42a5b4e9 100644
--- a/doc/source/index.rst
+++ b/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