diff --git a/doc/source/guides/multinode-lab.html b/doc/source/guides/multinode-lab.html
deleted file mode 100644
index 6a5f98c..0000000
--- a/doc/source/guides/multinode-lab.html
+++ /dev/null
@@ -1,336 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <title>Multi-Node Lab Server Guide - DevStack</title>
-    <meta name="description" content="">
-    <meta name="author" content="">
-
-    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
-    <!--[if lt IE 9]>
-      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
-    <![endif]-->
-
-    <!-- Le styles -->
-    <link href="../assets/css/bootstrap.css" rel="stylesheet">
-    <link href="../assets/css/local.css" rel="stylesheet">
-    <style type="text/css">
-      body { padding-top: 60px; }
-      dd { padding: 10px; }
-    </style>
-    
-    <!-- Le javascripts -->
-    <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
-    <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
-  </head>
-
-  <body>
-
-    <div class="navbar navbar-fixed-top">
-      <div class="navbar-inner">
-        <div class="container">
-          <a class="brand" href="/">DevStack</a>
-          <ul class="nav pull-right">
-            <li><a href="../overview.html">Overview</a></li>
-            <li><a href="../changes.html">Changes</a></li>
-            <li><a href="../faq.html">FAQ</a></li>
-            <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
-            <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
-          </ul>
-        </div>
-      </div>
-    </div>
-
-    <div class="container">
-
-      <section id="overview">
-        <h1>Multi-Node Lab: Serious Stuff</h1>
-        <p>Here is OpenStack in a realistic test configuration with multiple physical servers.</p>
-      </section>
-
-      <section id="prerequisites">
-        <div class="page-header">
-          <h2>Prerequisites <small>Linux & Network</small></h2>
-        </div>
-        
-        <h3>Minimal Install</h3>
-        <p>You need to have a system with a fresh install of Linux.  You can download the <a href="https://help.ubuntu.com/community/Installation/MinimalCD">Minimal CD</a> for Ubuntu releases since DevStack will download &amp; install all the additional dependencies.  The netinstall ISO is available for <a href="http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso">Fedora</a> and <a href="http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso">CentOS/RHEL</a>.</p>
-
-        <p>Install a couple of packages to bootstrap configuration:</p>
-        <pre>apt-get install -y git sudo || yum install -y git sudo</pre>
-
-        <h3>Network Configuration</h3>
-        <p>The first iteration of the lab uses OpenStack's FlatDHCP network controller so
-        only a single network will be required.  It should be on its own subnet without DHCP;
-        the host IPs and floating IP pool(s) will come out of this block. This example 
-        uses the following:</p>
-        <ul>
-          <li>Gateway: 192.168.42.1</li>
-          <li>Physical nodes: 192.168.42.11-192.168.42.99</li>
-          <li>Floating IPs: 192.168.42.128-192.168.42.254</li>
-        </ul>
-        <p>Configure each node with a static IP.
-        For Ubuntu edit <code>/etc/network/interfaces</code>:</p>
-
-        <pre>auto eth0
-iface eth0 inet static
-    address 192.168.42.11
-    netmask 255.255.255.0
-    gateway 192.168.42.1
-</pre>
-        <p>For Fedora and CentOS/RHEL edit
-        <code>/etc/sysconfig/network-scripts/ifcfg-eth0</code>:</p>
-
-        <pre>BOOTPROTO=static
-IPADDR=192.168.42.11
-NETMASK=255.255.255.0
-GATEWAY=192.168.42.1
-</pre>
-
-<!-- save these for the VLAN version
-   auto eth0.926
-   iface eth0.926 inet static
-           address 10.4.144.3
-           netmask 255.255.240.0
-           #gateway 10.4.144.1
-           up ifconfig eth0.926
-   
-   auto eth0.605
-   iface eth0.605 inet static
-           address 172.16.103.3
-           netmask 255.255.255.0
-           #gateway 172.16.103.1
-           up ifconfig eth0.605 up
--->
-
-      </section>
-
-      <section id="installation">
-        <div class="page-header">
-          <h2>Installation <small>shake and bake</small></h2>
-        </div>
-
-        <h3>Add the DevStack User</h3>
-        <p>OpenStack runs as a non-root user that has sudo access to root.  There is nothing special
-        about the name, we'll use <code>stack</code> here. Every node must use the same name and
-        preferably uid. If you created a user during the OS install you can use it and give it
-        sudo privileges below.  Otherwise create the stack user:</p>
-        <pre>groupadd stack
-useradd -g stack -s /bin/bash -d /opt/stack -m stack</pre>
-        <p>This user will be making many changes to your system during installation and operation
-        so it needs to have sudo privileges to root without a password:</p>
-        <pre>echo "stack ALL=(ALL) NOPASSWD: ALL" &gt;&gt; /etc/sudoers</pre>
-        <p>From here on use the <code>stack</code> user.  <b>Logout</b> and <b>login</b> as the 
-        <code>stack</code> user.</p>
-
-        <h3>Set Up Ssh</h3>
-        <p>Set up the stack user on each node with an ssh key for access:</p>
-        <pre>mkdir ~/.ssh; chmod 700 ~/.ssh
-echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyYjfgyPazTvGpd8OaAvtU2utL8W6gWC4JdRS1J95GhNNfQd657yO6s1AH5KYQWktcE6FO/xNUC2reEXSGC7ezy+sGO1kj9Limv5vrvNHvF1+wts0Cmyx61D2nQw35/Qz8BvpdJANL7VwP/cFI/p3yhvx2lsnjFE3hN8xRB2LtLUopUSVdBwACOVUmH2G+2BWMJDjVINd2DPqRIA4Zhy09KJ3O1Joabr0XpQL0yt/I9x8BVHdAx6l9U0tMg9dj5+tAjZvMAFfye3PJcYwwsfJoFxC8w/SLtqlFX7Ehw++8RtvomvuipLdmWCy+T9hIkl+gHYE4cS3OIqXH7f49jdJf jesse@spacey.local" > ~/.ssh/authorized_keys</pre>
-
-        <h3>Download DevStack</h3>
-        <p>Grab the latest version of DevStack:</p>
-        <pre>git clone https://git.openstack.org/openstack-dev/devstack
-cd devstack</pre>
-
-        <p>Up to this point all of the steps apply to each node in the cluster.  From here on
-        there are some differences between the cluster controller (aka 'head node') and the
-        compute nodes.</p>
-
-        <h3>Configure Cluster Controller</h3>
-        <p>The cluster controller runs all OpenStack services.  Configure the cluster controller's DevStack in <code>local.conf</code>:</p>
-        <pre>[[local|localrc]]
-HOST_IP=192.168.42.11
-FLAT_INTERFACE=eth0
-FIXED_RANGE=10.4.128.0/20
-FIXED_NETWORK_SIZE=4096
-FLOATING_RANGE=192.168.42.128/25
-MULTI_HOST=1
-LOGFILE=/opt/stack/logs/stack.sh.log
-ADMIN_PASSWORD=labstack
-MYSQL_PASSWORD=supersecret
-RABBIT_PASSWORD=supersecrete
-SERVICE_PASSWORD=supersecrete
-SERVICE_TOKEN=xyzpdqlazydog</pre>
-<!-- save for vlan
-FLAT_INTERFACE=eth0.926
--->
-
-        <p>In the multi-node configuration the first 10 or so IPs in the private subnet are usually reserved.  Add this to <code>local.sh</code> to have it run after every <code>stack.sh</code> run:</p>
-        <pre>for i in `seq 2 10`; do /opt/stack/nova/bin/nova-manage fixed reserve 10.4.128.$i; done</pre>
-
-        <p>Fire up OpenStack:</p>
-        <pre>./stack.sh</pre>
-        <p>A stream of activity ensues.  When complete you will see a summary of
-        <code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
-        shiny new OpenStack.  The most recent log file is available in <code>stack.sh.log</code>.</p>
-
-        <h3>Configure Compute Nodes</h3>
-        <p>The compute nodes only run the OpenStack worker services.  For additional machines, create a <code>local.conf</code> with:</p>
-        <pre>HOST_IP=192.168.42.12 # change this per compute node
-FLAT_INTERFACE=eth0
-FIXED_RANGE=10.4.128.0/20
-FIXED_NETWORK_SIZE=4096
-FLOATING_RANGE=192.168.42.128/25
-MULTI_HOST=1
-LOGFILE=/opt/stack/logs/stack.sh.log
-ADMIN_PASSWORD=labstack
-MYSQL_PASSWORD=supersecret
-RABBIT_PASSWORD=supersecrete
-SERVICE_PASSWORD=supersecrete
-SERVICE_TOKEN=xyzpdqlazydog
-DATABASE_TYPE=mysql
-SERVICE_HOST=192.168.42.11
-MYSQL_HOST=192.168.42.11
-RABBIT_HOST=192.168.42.11
-GLANCE_HOSTPORT=192.168.42.11:9292
-ENABLED_SERVICES=n-cpu,n-net,n-api,c-sch,c-api,c-vol
-NOVA_VNC_ENABLED=True
-NOVNCPROXY_URL="http://192.168.42.11:6080/vnc_auto.html"
-VNCSERVER_LISTEN=$HOST_IP
-VNCSERVER_PROXYCLIENT_ADDRESS=$VNCSERVER_LISTEN
-</pre>
-
-<!-- save for vlan
-FLAT_INTERFACE=eth0.926
--->
-
-        <p>Fire up OpenStack:</p>
-        <pre>./stack.sh</pre>
-        <p>A stream of activity ensues.  When complete you will see a summary of
-        <code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
-        shiny new OpenStack.  The most recent log file is available in <code>stack.sh.log</code>.</p>
-
-        <h3>Cleaning Up After DevStack</h3>
-        <p>Shutting down OpenStack is now as simple as running the included <code>unstack.sh</code> script:</p>
-        <pre>./unstack.sh</pre>
-
-        <p>A more aggressive cleanup can be performed using <code>clean.sh</code>.  It removes certain troublesome packages and attempts to leave the system in a state where changing the database or queue manager can be reliably performed.
-        <pre>./clean.sh</pre>
-
-        <p>Sometimes running instances are not cleaned up.  DevStack attempts to do this when it
-        runs but there are times it needs to still be done by hand:</p>
-        <pre>sudo rm -rf /etc/libvirt/qemu/inst*
-sudo virsh list | grep inst | awk '{print $1}' | xargs -n1 virsh destroy</pre>
-
-      </section>
-
-      <section id="options">
-        <div class="page-header">
-          <h2>Options <small>pimp your stack</small></h2>
-        </div>
-
-        <h3>Additional Users</h3>
-        <p>DevStack creates two OpenStack users (<code>admin</code> and <code>demo</code>) and two tenants (also <code>admin</code> and <code>demo</code>).  <code>admin</code> is exactly what it sounds like, a privileged administrative account that is a member of both the <code>admin</code> and <code>demo</code> tenants.  <code>demo</code> is a normal user account that is only a member of the <code>demo</code> tenant.  Creating additional OpenStack users can be done through the dashboard, sometimes it is easier to do them in bulk from a script, especially since they get blown away every time
-        <code>stack.sh</code> runs.  The following steps are ripe for scripting:</p>
-        <pre># Get admin creds
-. openrc admin admin
-        
-# List existing tenants
-keystone tenant-list
-
-# List existing users
-keystone user-list
-
-# Add a user and tenant
-NAME=bob
-PASSWORD=BigSecrete
-TENANT=$NAME
-keystone tenant-create --name=$NAME
-keystone user-create --name=$NAME --pass=$PASSWORD
-keystone user-role-add --user-id=&lt;bob-user-id&gt; --tenant-id=&lt;bob-tenant-id&gt; --role-id=&lt;member-role-id&gt;
-# member-role-id comes from the existing member role created by stack.sh
-# keystone role-list</pre>
-
-        <h3>Swift</h3>
-        <p>Swift requires a significant amount of resources and is disabled by default in DevStack.
-        The support in DevStack is geared toward a minimal installation but can be used for
-        testing.  To implement a true multi-node test of Swift required more than DevStack provides.  
-        Enabling it is as simple as enabling the <code>swift</code> service in <code>local.conf</code>:
-        <pre>enable_service s-proxy s-object s-container s-account</pre>
-
-        <p>Swift will put its data files in <code>SWIFT_DATA_DIR</code> (default <code>/opt/stack/data/swift</code>).
-        The size of the data 'partition' created (really a loop-mounted file) is set by
-        <code>SWIFT_LOOPBACK_DISK_SIZE</code>.  The Swift config files are located in 
-        <code>SWIFT_CONFIG_DIR</code> (default <code>/etc/swift</code>).  All of these settings can be overridden in
-        (wait for it...) <code>local.conf</code>.</p>
-
-        <h3>Volumes</h3>
-        <p>DevStack will automatically use an existing LVM volume group named <code>stack-volumes</code> 
-        to store cloud-created volumes. If <code>stack-volumes</code> doesn't exist, DevStack 
-        will set up a 5Gb loop-mounted file to contain it.  This obviously limits the
-        number and size of volumes that can be created inside OpenStack.  The size can be
-        overridden by setting <code>VOLUME_BACKING_FILE_SIZE</code> in <code>local.conf</code>.</p>
-
-        <p><code>stack-volumes</code> can be pre-created on any physical volume supported by
-        Linux's LVM.  The name of the volume group can be changed by setting <code>VOLUME_GROUP</code>
-        in <code>localrc</code>. <code>stack.sh</code> deletes
-        all logical volumes in <code>VOLUME_GROUP</code> that begin with 
-        <code>VOLUME_NAME_PREFIX</code> as part of cleaning up from previous runs.
-        It is recommended to not use the root volume group as <code>VOLUME_GROUP</code>.</p>
-
-        <p>The details of creating the volume group depends on the server hardware involved 
-        but looks something like this:</p>
-        <pre>pvcreate /dev/sdc
-vgcreate stack-volumes /dev/sdc</pre>
-
-        <h3>Syslog</h3>
-        <p>DevStack is capable of using <code>rsyslog</code> to aggregate logging across the cluster.
-        It is off by default; to turn it on set <code>SYSLOG=True</code> in <code>local.conf</code>.
-        <code>SYSLOG_HOST</code> defaults to <code>HOST_IP</code>; on the compute nodes it 
-        must be set to the IP of the cluster controller to send syslog output there.  In the example
-        above, add this to the compute node <code>local.conf</code>:</p>
-        <pre>SYSLOG_HOST=192.168.42.11</pre>
-
-        <h3>Using Alternate Repositories/Branches</h3>
-        <p>The git repositories for all of the OpenStack services are defined in <code>stackrc</code>.
-        Since this file is a part of the DevStack package changes to it will probably be overwritten
-        as updates are applied.  Every setting in <code>stackrc</code> can be redefined in
-        <code>local.conf</code>.</p>
-
-        <p>To change the repository or branch that a particular OpenStack service is created from,
-        simply change the value of <code>*_REPO</code> or <code>*_BRANCH</code> corresponding to
-        that service.</p>
-
-        <p>After making changes to the repository or branch, if <code>RECLONE</code> is not set
-        in <code>localrc</code> it may be necessary to remove the corresponding directory from
-        <code>/opt/stack</code> to force git to re-clone the repository.</p>
-
-        <p>For example, to pull Nova from a proposed release candidate in the primary Nova 
-        repository:</p>
-        <pre>NOVA_BRANCH=rc-proposed</pre>
-
-        <p>To pull Glance from an experimental fork:</p>
-        <pre>GLANCE_BRANCH=try-something-big
-GLANCE_REPO=https://github.com/mcuser/glance.git</pre>
-
-      </section>
-
-      <section id="Notes">
-        <div class="page-header">
-          <h2>Notes <small>stuff you might need to know</small></h2>
-        </div>
-
-        <h3>Reset the Bridge</h3>
-        <p>How to reset the bridge configuration:</p>
-        <pre>sudo brctl delif br100 eth0.926
-sudo ip link set dev br100 down
-sudo brctl delbr br100</pre>
-<!--
-   sudo rm /etc/libvirt/qemu/*.xml
--->
-
-        <h3>Set MySQL Password</h3>
-        <p>If you forgot to set the root password you can do this:</p>
-        <pre>mysqladmin -u root -pnova password 'supersecret'</pre>
-
-      </section>
-
-      <footer>
-        <p>&copy; Openstack Foundation 2011-2014 &mdash; An <a href="https://www.openstack.org/">OpenStack</a> <a href="https://wiki.openstack.org/wiki/Programs">program</a></p>
-      </footer>
-
-    </div> <!-- /container -->
-
-  </body>
-</html>
diff --git a/doc/source/guides/multinode-lab.rst b/doc/source/guides/multinode-lab.rst
new file mode 100644
index 0000000..c7901a2
--- /dev/null
+++ b/doc/source/guides/multinode-lab.rst
@@ -0,0 +1,382 @@
+`DevStack </>`__
+
+-  `Overview <../overview.html>`__
+-  `Changes <../changes.html>`__
+-  `FAQ <../faq.html>`__
+-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
+-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+
+Multi-Node Lab: Serious Stuff
+=============================
+
+Here is OpenStack in a realistic test configuration with multiple
+physical servers.
+
+Prerequisites Linux & Network
+-----------------------------
+
+Minimal Install
+~~~~~~~~~~~~~~~
+
+You need to have a system with a fresh install of Linux. You can
+download the `Minimal
+CD <https://help.ubuntu.com/community/Installation/MinimalCD>`__ for
+Ubuntu releases since DevStack will download & install all the
+additional dependencies. The netinstall ISO is available for
+`Fedora <http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso>`__
+and
+`CentOS/RHEL <http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso>`__.
+
+Install a couple of packages to bootstrap configuration:
+
+::
+
+    apt-get install -y git sudo || yum install -y git sudo
+
+Network Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+The first iteration of the lab uses OpenStack's FlatDHCP network
+controller so only a single network will be required. It should be on
+its own subnet without DHCP; the host IPs and floating IP pool(s) will
+come out of this block. This example uses the following:
+
+-  Gateway: 192.168.42.1
+-  Physical nodes: 192.168.42.11-192.168.42.99
+-  Floating IPs: 192.168.42.128-192.168.42.254
+
+Configure each node with a static IP. For Ubuntu edit
+``/etc/network/interfaces``:
+
+::
+
+    auto eth0
+    iface eth0 inet static
+        address 192.168.42.11
+        netmask 255.255.255.0
+        gateway 192.168.42.1
+
+For Fedora and CentOS/RHEL edit
+``/etc/sysconfig/network-scripts/ifcfg-eth0``:
+
+::
+
+    BOOTPROTO=static
+    IPADDR=192.168.42.11
+    NETMASK=255.255.255.0
+    GATEWAY=192.168.42.1
+
+Installation shake and bake
+---------------------------
+
+Add the DevStack User
+~~~~~~~~~~~~~~~~~~~~~
+
+OpenStack runs as a non-root user that has sudo access to root. There is
+nothing special about the name, we'll use ``stack`` here. Every node
+must use the same name and preferably uid. If you created a user during
+the OS install you can use it and give it sudo privileges below.
+Otherwise create the stack user:
+
+::
+
+    groupadd stack
+    useradd -g stack -s /bin/bash -d /opt/stack -m stack
+
+This user will be making many changes to your system during installation
+and operation so it needs to have sudo privileges to root without a
+password:
+
+::
+
+    echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+From here on use the ``stack`` user. **Logout** and **login** as the
+``stack`` user.
+
+Set Up Ssh
+~~~~~~~~~~
+
+Set up the stack user on each node with an ssh key for access:
+
+::
+
+    mkdir ~/.ssh; chmod 700 ~/.ssh
+    echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyYjfgyPazTvGpd8OaAvtU2utL8W6gWC4JdRS1J95GhNNfQd657yO6s1AH5KYQWktcE6FO/xNUC2reEXSGC7ezy+sGO1kj9Limv5vrvNHvF1+wts0Cmyx61D2nQw35/Qz8BvpdJANL7VwP/cFI/p3yhvx2lsnjFE3hN8xRB2LtLUopUSVdBwACOVUmH2G+2BWMJDjVINd2DPqRIA4Zhy09KJ3O1Joabr0XpQL0yt/I9x8BVHdAx6l9U0tMg9dj5+tAjZvMAFfye3PJcYwwsfJoFxC8w/SLtqlFX7Ehw++8RtvomvuipLdmWCy+T9hIkl+gHYE4cS3OIqXH7f49jdJf jesse@spacey.local" > ~/.ssh/authorized_keys
+
+Download DevStack
+~~~~~~~~~~~~~~~~~
+
+Grab the latest version of DevStack:
+
+::
+
+    git clone https://git.openstack.org/openstack-dev/devstack
+    cd devstack
+
+Up to this point all of the steps apply to each node in the cluster.
+From here on there are some differences between the cluster controller
+(aka 'head node') and the compute nodes.
+
+Configure Cluster Controller
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The cluster controller runs all OpenStack services. Configure the
+cluster controller's DevStack in ``local.conf``:
+
+::
+
+    [[local|localrc]]
+    HOST_IP=192.168.42.11
+    FLAT_INTERFACE=eth0
+    FIXED_RANGE=10.4.128.0/20
+    FIXED_NETWORK_SIZE=4096
+    FLOATING_RANGE=192.168.42.128/25
+    MULTI_HOST=1
+    LOGFILE=/opt/stack/logs/stack.sh.log
+    ADMIN_PASSWORD=labstack
+    MYSQL_PASSWORD=supersecret
+    RABBIT_PASSWORD=supersecrete
+    SERVICE_PASSWORD=supersecrete
+    SERVICE_TOKEN=xyzpdqlazydog
+
+In the multi-node configuration the first 10 or so IPs in the private
+subnet are usually reserved. Add this to ``local.sh`` to have it run
+after every ``stack.sh`` run:
+
+::
+
+    for i in `seq 2 10`; do /opt/stack/nova/bin/nova-manage fixed reserve 10.4.128.$i; done
+
+Fire up OpenStack:
+
+::
+
+    ./stack.sh
+
+A stream of activity ensues. When complete you will see a summary of
+``stack.sh``'s work, including the relevant URLs, accounts and passwords
+to poke at your shiny new OpenStack. The most recent log file is
+available in ``stack.sh.log``.
+
+Configure Compute Nodes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The compute nodes only run the OpenStack worker services. For additional
+machines, create a ``local.conf`` with:
+
+::
+
+    HOST_IP=192.168.42.12 # change this per compute node
+    FLAT_INTERFACE=eth0
+    FIXED_RANGE=10.4.128.0/20
+    FIXED_NETWORK_SIZE=4096
+    FLOATING_RANGE=192.168.42.128/25
+    MULTI_HOST=1
+    LOGFILE=/opt/stack/logs/stack.sh.log
+    ADMIN_PASSWORD=labstack
+    MYSQL_PASSWORD=supersecret
+    RABBIT_PASSWORD=supersecrete
+    SERVICE_PASSWORD=supersecrete
+    SERVICE_TOKEN=xyzpdqlazydog
+    DATABASE_TYPE=mysql
+    SERVICE_HOST=192.168.42.11
+    MYSQL_HOST=192.168.42.11
+    RABBIT_HOST=192.168.42.11
+    GLANCE_HOSTPORT=192.168.42.11:9292
+    ENABLED_SERVICES=n-cpu,n-net,n-api,c-sch,c-api,c-vol
+    NOVA_VNC_ENABLED=True
+    NOVNCPROXY_URL="http://192.168.42.11:6080/vnc_auto.html"
+    VNCSERVER_LISTEN=$HOST_IP
+    VNCSERVER_PROXYCLIENT_ADDRESS=$VNCSERVER_LISTEN
+
+Fire up OpenStack:
+
+::
+
+    ./stack.sh
+
+A stream of activity ensues. When complete you will see a summary of
+``stack.sh``'s work, including the relevant URLs, accounts and passwords
+to poke at your shiny new OpenStack. The most recent log file is
+available in ``stack.sh.log``.
+
+Cleaning Up After DevStack
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Shutting down OpenStack is now as simple as running the included
+``unstack.sh`` script:
+
+::
+
+    ./unstack.sh
+
+A more aggressive cleanup can be performed using ``clean.sh``. It
+removes certain troublesome packages and attempts to leave the system in
+a state where changing the database or queue manager can be reliably
+performed.
+
+::
+
+    ./clean.sh
+
+Sometimes running instances are not cleaned up. DevStack attempts to do
+this when it runs but there are times it needs to still be done by hand:
+
+::
+
+    sudo rm -rf /etc/libvirt/qemu/inst*
+    sudo virsh list | grep inst | awk '{print $1}' | xargs -n1 virsh destroy
+
+Options pimp your stack
+-----------------------
+
+Additional Users
+~~~~~~~~~~~~~~~~
+
+DevStack creates two OpenStack users (``admin`` and ``demo``) and two
+tenants (also ``admin`` and ``demo``). ``admin`` is exactly what it
+sounds like, a privileged administrative account that is a member of
+both the ``admin`` and ``demo`` tenants. ``demo`` is a normal user
+account that is only a member of the ``demo`` tenant. Creating
+additional OpenStack users can be done through the dashboard, sometimes
+it is easier to do them in bulk from a script, especially since they get
+blown away every time ``stack.sh`` runs. The following steps are ripe
+for scripting:
+
+::
+
+    # Get admin creds
+    . openrc admin admin
+            
+    # List existing tenants
+    keystone tenant-list
+
+    # List existing users
+    keystone user-list
+
+    # Add a user and tenant
+    NAME=bob
+    PASSWORD=BigSecrete
+    TENANT=$NAME
+    keystone tenant-create --name=$NAME
+    keystone user-create --name=$NAME --pass=$PASSWORD
+    keystone user-role-add --user-id=<bob-user-id> --tenant-id=<bob-tenant-id> --role-id=<member-role-id>
+    # member-role-id comes from the existing member role created by stack.sh
+    # keystone role-list
+
+Swift
+~~~~~
+
+Swift requires a significant amount of resources and is disabled by
+default in DevStack. The support in DevStack is geared toward a minimal
+installation but can be used for testing. To implement a true multi-node
+test of Swift required more than DevStack provides. Enabling it is as
+simple as enabling the ``swift`` service in ``local.conf``:
+
+::
+
+    enable_service s-proxy s-object s-container s-account
+
+Swift will put its data files in ``SWIFT_DATA_DIR`` (default
+``/opt/stack/data/swift``). The size of the data 'partition' created
+(really a loop-mounted file) is set by ``SWIFT_LOOPBACK_DISK_SIZE``. The
+Swift config files are located in ``SWIFT_CONFIG_DIR`` (default
+``/etc/swift``). All of these settings can be overridden in (wait for
+it...) ``local.conf``.
+
+Volumes
+~~~~~~~
+
+DevStack will automatically use an existing LVM volume group named
+``stack-volumes`` to store cloud-created volumes. If ``stack-volumes``
+doesn't exist, DevStack will set up a 5Gb loop-mounted file to contain
+it. This obviously limits the number and size of volumes that can be
+created inside OpenStack. The size can be overridden by setting
+``VOLUME_BACKING_FILE_SIZE`` in ``local.conf``.
+
+``stack-volumes`` can be pre-created on any physical volume supported by
+Linux's LVM. The name of the volume group can be changed by setting
+``VOLUME_GROUP`` in ``localrc``. ``stack.sh`` deletes all logical
+volumes in ``VOLUME_GROUP`` that begin with ``VOLUME_NAME_PREFIX`` as
+part of cleaning up from previous runs. It is recommended to not use the
+root volume group as ``VOLUME_GROUP``.
+
+The details of creating the volume group depends on the server hardware
+involved but looks something like this:
+
+::
+
+    pvcreate /dev/sdc
+    vgcreate stack-volumes /dev/sdc
+
+Syslog
+~~~~~~
+
+DevStack is capable of using ``rsyslog`` to aggregate logging across the
+cluster. It is off by default; to turn it on set ``SYSLOG=True`` in
+``local.conf``. ``SYSLOG_HOST`` defaults to ``HOST_IP``; on the compute
+nodes it must be set to the IP of the cluster controller to send syslog
+output there. In the example above, add this to the compute node
+``local.conf``:
+
+::
+
+    SYSLOG_HOST=192.168.42.11
+
+Using Alternate Repositories/Branches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The git repositories for all of the OpenStack services are defined in
+``stackrc``. Since this file is a part of the DevStack package changes
+to it will probably be overwritten as updates are applied. Every setting
+in ``stackrc`` can be redefined in ``local.conf``.
+
+To change the repository or branch that a particular OpenStack service
+is created from, simply change the value of ``*_REPO`` or ``*_BRANCH``
+corresponding to that service.
+
+After making changes to the repository or branch, if ``RECLONE`` is not
+set in ``localrc`` it may be necessary to remove the corresponding
+directory from ``/opt/stack`` to force git to re-clone the repository.
+
+For example, to pull Nova from a proposed release candidate in the
+primary Nova repository:
+
+::
+
+    NOVA_BRANCH=rc-proposed
+
+To pull Glance from an experimental fork:
+
+::
+
+    GLANCE_BRANCH=try-something-big
+    GLANCE_REPO=https://github.com/mcuser/glance.git
+
+Notes stuff you might need to know
+----------------------------------
+
+Reset the Bridge
+~~~~~~~~~~~~~~~~
+
+How to reset the bridge configuration:
+
+::
+
+    sudo brctl delif br100 eth0.926
+    sudo ip link set dev br100 down
+    sudo brctl delbr br100
+
+Set MySQL Password
+~~~~~~~~~~~~~~~~~~
+
+If you forgot to set the root password you can do this:
+
+::
+
+    mysqladmin -u root -pnova password 'supersecret'
+
+© Openstack Foundation 2011-2014 — An
+`OpenStack <https://www.openstack.org/>`__
+`program <https://wiki.openstack.org/wiki/Programs>`__
diff --git a/doc/source/guides/pxe-boot.html b/doc/source/guides/pxe-boot.html
deleted file mode 100644
index d52b25f..0000000
--- a/doc/source/guides/pxe-boot.html
+++ /dev/null
@@ -1,147 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <title>PXE Boot Server Guide - DevStack</title>
-    <meta name="description" content="">
-    <meta name="author" content="">
-
-    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
-    <!--[if lt IE 9]>
-      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
-    <![endif]-->
-
-    <!-- Le styles -->
-    <link href="../assets/css/bootstrap.css" rel="stylesheet">
-    <link href="../assets/css/local.css" rel="stylesheet">
-    <style type="text/css">
-      body { padding-top: 60px; }
-      dd { padding: 10px; }
-    </style>
-    
-    <!-- Le javascripts -->
-    <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
-    <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
-  </head>
-
-  <body>
-
-    <div class="navbar navbar-fixed-top">
-      <div class="navbar-inner">
-        <div class="container">
-          <a class="brand" href="/">DevStack</a>
-          <ul class="nav pull-right">
-            <li><a href="../overview.html">Overview</a></li>
-            <li><a href="../changes.html">Changes</a></li>
-            <li><a href="../faq.html">FAQ</a></li>
-            <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
-            <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
-          </ul>
-        </div>
-      </div>
-    </div>
-
-    <div class="container">
-      <section id="overview">
-        <h1>PXE Boot Server Guide: Magic Dust for Network Boot</h1>
-        <p>Boot DevStack from a PXE server to a RAM disk.</p>
-      </section>
-
-      <section id="requirements">
-        <div class="page-header">
-          <h2>Prerequisites <small>Hardware & OpenWRT</small></h2>
-        </div>
-        
-        <h3>Hardware</h3>
-        <p>The whole point of this exercise is to have a highly portable boot server, so using a small router with a USB port is the desired platform.  This guide uses a Buffalo WZR-HP-G300NH as an example, but it is easily generalized for other supported platforms. See openwrt.org for more.</p>
-        
-        <h3>OpenWRT</h3>
-        <p>Any recent 'Backfire' build of OpenWRT will work for the boot server project.  We build from trunk and have made the images available at <a href="http://openwrt.xr7.org/openwrt">http://openwrt.xr7.org/openwrt</a>.</p>
-      </section>
-
-      <section id="installation">
-        <div class="page-header">
-          <h2>Installation <small>bit blasting</small></h2>
-        </div>
-
-        <h3>Install the Image</h3>
-        <p>This process follows <a href="http://wiki.openwrt.org/toh/buffalo/wzr-hp-g300h">the OpenWRT doc OEM Install</a> to tftp the new image onto the router.  You need a computer to set up the router, we assume it is a recent Linux or OS/X installation.</p>
-        <ul>
-          <li>Get openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
-            <pre>wget http://openwrt.xr7.org/openwrt/ar71xx/openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin</pre>
-          </li>
-          <li>Connect computer to LAN port 4 (closest to WAN port)</li>
-          <li>Set computer interface to IP address in the 192.168.11.2</li>
-          <li>Add static arp entry for router
-            <pre>arp -s 192.168.11.1 &lt;mac-address&gt;</pre>
-          </li>
-          <li>Start TFTP transfer attempt
-            <pre>tftp 192.168.11.1
-binary
-rexmt 1
-timeout 60
-put openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin</pre>
-          </li>
-          <li>Power on router. Router will reboot and initialize on 192.168.1.1.</li>
-          <li>Delete static arp entry for router
-            <pre>arp -d 192.168.11.1</pre>
-          </li>
-          <li>Set computer to DHCP, connect and telnet to router and set root password.</li>
-        </ul>
-
-        <h3>Configure the Router</h3>
-        <ul>
-          <li>Update <code>/etc/opkg.conf</code> to point to our repo:
-            <pre>src/gz packages http://192.168.5.13/openwrt/build/ar71xx/packages</pre>
-          </li>
-          <li>Configure anon mounts:
-            <pre>uci delete fstab.@mount[0]
-uci commit fstab
-/etc/init.d/fstab restart</pre>
-          </li>
-          <li>Reset the DHCP address range.  DevStack will claim the upper 
-            /25 of the router's LAN address space for floating IPs so the
-            default DHCP address range needs to be moved:
-            <pre>uci set dhcp.lan.start=65
-uci set dhcp.lan.limit=60
-uci commit dhcp</pre>
-          </li>
-          <li>Enable TFTP:
-            <pre>uci set dhcp.@dnsmasq[0].enable_tftp=1
-uci set dhcp.@dnsmasq[0].tftp_root=/mnt/sda1/tftpboot
-uci set dhcp.@dnsmasq[0].dhcp_boot=pxelinux.0
-uci commit dhcp
-/etc/init.d/dnsmasq restart</pre>
-          </li>
-        </ul>
-
-        <h3>Set Up tftpboot</h3>
-        <ul>
-          <li>Create the <code>/tmp/tftpboot</code> structure and populate it:
-            <pre>cd ~/devstack
-tools/build_pxe_boot.sh /tmp</pre>
-            This calls <code>tools/build_ramdisk.sh</code> to create a 2GB ramdisk 
-            containing a complete development Oneiric OS plus the 
-            OpenStack code checkouts.
-          </li>
-          <li>Copy <code>tftpboot</code> to a USB drive:
-            <pre>mount /dev/sdb1 /mnt/tmp
-rsync -a /tmp/tftpboot/ /mnt/tmp/tftpboot/
-umount /mnt/tmp</pre>
-          </li>
-          <li>Plug USB drive into router.  It will be automounted and is ready to serve content.</li>
-        </ul>
-
-        <p>Now <a href="ramdisk.html">return</a> to the RAM disk Guide to kick
-           off your DevStack experience.</p>
-
-      </section>
-
-      <footer>
-        <p>&copy; Openstack Foundation 2011-2013 &mdash; this is not an official OpenStack project...</p>
-      </footer>
-
-    </div> <!-- /container -->
-
-  </body>
-</html>
diff --git a/doc/source/guides/pxe-boot.rst b/doc/source/guides/pxe-boot.rst
new file mode 100644
index 0000000..584e558
--- /dev/null
+++ b/doc/source/guides/pxe-boot.rst
@@ -0,0 +1,143 @@
+`DevStack </>`__
+
+-  `Overview <../overview.html>`__
+-  `Changes <../changes.html>`__
+-  `FAQ <../faq.html>`__
+-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
+-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+
+PXE Boot Server Guide: Magic Dust for Network Boot
+==================================================
+
+Boot DevStack from a PXE server to a RAM disk.
+
+Prerequisites Hardware & OpenWRT
+--------------------------------
+
+Hardware
+~~~~~~~~
+
+The whole point of this exercise is to have a highly portable boot
+server, so using a small router with a USB port is the desired platform.
+This guide uses a Buffalo WZR-HP-G300NH as an example, but it is easily
+generalized for other supported platforms. See openwrt.org for more.
+
+OpenWRT
+~~~~~~~
+
+Any recent 'Backfire' build of OpenWRT will work for the boot server
+project. We build from trunk and have made the images available at
+`http://openwrt.xr7.org/openwrt <http://openwrt.xr7.org/openwrt>`__.
+
+Installation bit blasting
+-------------------------
+
+Install the Image
+~~~~~~~~~~~~~~~~~
+
+This process follows `the OpenWRT doc OEM
+Install <http://wiki.openwrt.org/toh/buffalo/wzr-hp-g300h>`__ to tftp
+the new image onto the router. You need a computer to set up the router,
+we assume it is a recent Linux or OS/X installation.
+
+-  Get openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
+
+   ::
+
+       wget http://openwrt.xr7.org/openwrt/ar71xx/openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
+
+-  Connect computer to LAN port 4 (closest to WAN port)
+-  Set computer interface to IP address in the 192.168.11.2
+-  Add static arp entry for router
+
+   ::
+
+       arp -s 192.168.11.1 <mac-address>
+
+-  Start TFTP transfer attempt
+
+   ::
+
+       tftp 192.168.11.1
+       binary
+       rexmt 1
+       timeout 60
+       put openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
+
+-  Power on router. Router will reboot and initialize on 192.168.1.1.
+-  Delete static arp entry for router
+
+   ::
+
+       arp -d 192.168.11.1
+
+-  Set computer to DHCP, connect and telnet to router and set root
+   password.
+
+Configure the Router
+~~~~~~~~~~~~~~~~~~~~
+
+-  Update ``/etc/opkg.conf`` to point to our repo:
+
+   ::
+
+       src/gz packages http://192.168.5.13/openwrt/build/ar71xx/packages
+
+-  Configure anon mounts:
+
+   ::
+
+       uci delete fstab.@mount[0]
+       uci commit fstab
+       /etc/init.d/fstab restart
+
+-  Reset the DHCP address range. DevStack will claim the upper /25 of
+   the router's LAN address space for floating IPs so the default DHCP
+   address range needs to be moved:
+
+   ::
+
+       uci set dhcp.lan.start=65
+       uci set dhcp.lan.limit=60
+       uci commit dhcp
+
+-  Enable TFTP:
+
+   ::
+
+       uci set dhcp.@dnsmasq[0].enable_tftp=1
+       uci set dhcp.@dnsmasq[0].tftp_root=/mnt/sda1/tftpboot
+       uci set dhcp.@dnsmasq[0].dhcp_boot=pxelinux.0
+       uci commit dhcp
+       /etc/init.d/dnsmasq restart
+
+Set Up tftpboot
+~~~~~~~~~~~~~~~
+
+-  Create the ``/tmp/tftpboot`` structure and populate it:
+
+   ::
+
+       cd ~/devstack
+       tools/build_pxe_boot.sh /tmp
+
+   This calls ``tools/build_ramdisk.sh`` to create a 2GB ramdisk
+   containing a complete development Oneiric OS plus the OpenStack code
+   checkouts.
+
+-  Copy ``tftpboot`` to a USB drive:
+
+   ::
+
+       mount /dev/sdb1 /mnt/tmp
+       rsync -a /tmp/tftpboot/ /mnt/tmp/tftpboot/
+       umount /mnt/tmp
+
+-  Plug USB drive into router. It will be automounted and is ready to
+   serve content.
+
+Now `return <ramdisk.html>`__ to the RAM disk Guide to kick off your
+DevStack experience.
+
+© Openstack Foundation 2011-2013 — this is not an official OpenStack
+project...
diff --git a/doc/source/guides/ramdisk.html b/doc/source/guides/ramdisk.html
deleted file mode 100644
index 23239e2..0000000
--- a/doc/source/guides/ramdisk.html
+++ /dev/null
@@ -1,119 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <title>RAMdisk Boot Guide - DevStack</title>
-    <meta name="description" content="">
-    <meta name="author" content="">
-
-    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
-    <!--[if lt IE 9]>
-      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
-    <![endif]-->
-
-    <!-- Le styles -->
-    <link href="../assets/css/bootstrap.css" rel="stylesheet">
-    <link href="../assets/css/local.css" rel="stylesheet">
-    <style type="text/css">
-      body { padding-top: 60px; }
-      dd { padding: 10px; }
-    </style>
-    
-    <!-- Le javascripts -->
-    <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
-    <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
-  </head>
-
-  <body>
-
-    <div class="navbar navbar-fixed-top">
-      <div class="navbar-inner">
-        <div class="container">
-          <a class="brand" href="/">DevStack</a>
-          <ul class="nav pull-right">
-            <li><a href="../overview.html">Overview</a></li>
-            <li><a href="../changes.html">Changes</a></li>
-            <li><a href="../faq.html">FAQ</a></li>
-            <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
-            <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
-          </ul>
-        </div>
-      </div>
-    </div>
-
-    <div class="container">
-      <section id="overview">
-        <h1>Stack-in-a-Box: Try before you mkfs</h1>
-        <p>Run DevStack from a RAM disk to give it a whirl before making the 
-           commitment to install it.  We'll cover booting from a USB drive or 
-           over the network via PXE.  We'll even thow in configuring a home
-           router to handle the PXE boot.  You will need a minimum of 3GB 
-           for both of these configurations as the RAM disk itself is 2GB.</p>
-      </section>
-
-      <section id="requirements">
-        <div class="page-header">
-          <h2>Prerequisites <small>Hardware</small></h2>
-        </div>
-        
-        <h3>USB Boot</h3>
-        <p><a href="usb-boot.html">This guide</a> covers the creation of a bootable USB drive.  Your 
-        computer BIOS must support booting from USB.</p>
-        
-        <h3>PXE Boot</h3>
-        <p><a href="pxe-boot.html">This guide</a> covers the installation of OpenWRT on a home router
-        and configuring it as a PXE server, plus the creation of the
-        boot images and PXE support files.
-      </section>
-
-      <section id="installation">
-        <div class="page-header">
-          <h2>Installation <small>bit blasting</small></h2>
-        </div>
-
-        <h3>Install DevStack</h3>
-        <p>Grab the latest version of DevStack via https:</p>
-		<pre>sudo apt-get install git -y
-git clone https://git.openstack.org/openstack-dev/devstack
-cd devstack</pre>
-
-        <h3>Prepare the Boot RAMdisk</h3>
-        <p>Pick your boot method and follow the guide to prepare to build
-           the RAM disk and set up the boot process:</p>
-        <ul>
-          <li><a href="usb-boot.html">USB boot</a></li>
-          <li><a href="pxe-boot.html">PXE boot</a></li>
-        </ul>
-
-        <h3>Fire It Up</h3>
-        <ul>
-          <li>Boot the computer into the RAM disk.  The details will vary from
-              machine to machine but most BIOSes have a method to select the
-              boot device, often by pressing F12 during POST.</li>
-          <li>Select 'DevStack' from the Boot Menu.</li>
-          <li>Log in with the 'stack' user and 'pass' password.</li>
-          <li>Create <code>devstack/localrc</code> if you wish to change any 
-              of the configuration variables.  You will probably want to at 
-              least set the admin login password to something memorable rather 
-              than the default 20 random characters:
-            <pre>ADMIN_PASSWORD=openstack</pre>
-          </li>
-          <li>Fire up OpenStack!
-            <pre>./run.sh</pre>
-          </li>
-          <li>See the processes running in screen:
-            <pre>screen -x</pre>
-          </li>
-          <li>Connect to the dashboard at <code>http://&lt;ip-address&gt;/</code></li>
-        </ul>
-
-      </section>
-
-      <footer>
-        <p>&copy; Openstack Foundation 2011-2013 &mdash; this is not an official OpenStack project...</p>
-      </footer>
-
-    </div> <!-- /container -->
-
-  </body>
-</html>
diff --git a/doc/source/guides/ramdisk.rst b/doc/source/guides/ramdisk.rst
new file mode 100644
index 0000000..82147a8
--- /dev/null
+++ b/doc/source/guides/ramdisk.rst
@@ -0,0 +1,89 @@
+`DevStack </>`__
+
+-  `Overview <../overview.html>`__
+-  `Changes <../changes.html>`__
+-  `FAQ <../faq.html>`__
+-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
+-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+
+Stack-in-a-Box: Try before you mkfs
+===================================
+
+Run DevStack from a RAM disk to give it a whirl before making the
+commitment to install it. We'll cover booting from a USB drive or over
+the network via PXE. We'll even thow in configuring a home router to
+handle the PXE boot. You will need a minimum of 3GB for both of these
+configurations as the RAM disk itself is 2GB.
+
+Prerequisites Hardware
+----------------------
+
+USB Boot
+~~~~~~~~
+
+`This guide <usb-boot.html>`__ covers the creation of a bootable USB
+drive. Your computer BIOS must support booting from USB.
+
+PXE Boot
+~~~~~~~~
+
+`This guide <pxe-boot.html>`__ covers the installation of OpenWRT on a
+home router and configuring it as a PXE server, plus the creation of the
+boot images and PXE support files.
+
+Installation bit blasting
+-------------------------
+
+Install DevStack
+~~~~~~~~~~~~~~~~
+
+Grab the latest version of DevStack via https:
+
+::
+
+    sudo apt-get install git -y
+    git clone https://git.openstack.org/openstack-dev/devstack
+    cd devstack
+
+Prepare the Boot RAMdisk
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pick your boot method and follow the guide to prepare to build the RAM
+disk and set up the boot process:
+
+-  `USB boot <usb-boot.html>`__
+-  `PXE boot <pxe-boot.html>`__
+
+Fire It Up
+~~~~~~~~~~
+
+-  Boot the computer into the RAM disk. The details will vary from
+   machine to machine but most BIOSes have a method to select the boot
+   device, often by pressing F12 during POST.
+-  Select 'DevStack' from the Boot Menu.
+-  Log in with the 'stack' user and 'pass' password.
+-  Create ``devstack/localrc`` if you wish to change any of the
+   configuration variables. You will probably want to at least set the
+   admin login password to something memorable rather than the default
+   20 random characters:
+
+   ::
+
+       ADMIN_PASSWORD=openstack
+
+-  Fire up OpenStack!
+
+   ::
+
+       ./run.sh
+
+-  See the processes running in screen:
+
+   ::
+
+       screen -x
+
+-  Connect to the dashboard at ``http://<ip-address>/``
+
+© Openstack Foundation 2011-2013 — this is not an official OpenStack
+project...
diff --git a/doc/source/guides/single-machine.html b/doc/source/guides/single-machine.html
deleted file mode 100644
index 06cc981..0000000
--- a/doc/source/guides/single-machine.html
+++ /dev/null
@@ -1,131 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <title>Single Machine Guide - DevStack</title>
-    <meta name="description" content="">
-    <meta name="author" content="">
-
-    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
-    <!--[if lt IE 9]>
-      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
-    <![endif]-->
-
-    <!-- Le styles -->
-    <link href="../assets/css/bootstrap.css" rel="stylesheet">
-    <link href="../assets/css/local.css" rel="stylesheet">
-    <style type="text/css">
-      body { padding-top: 60px; }
-      dd { padding: 10px; }
-    </style>
-    
-    <!-- Le javascripts -->
-    <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
-    <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
-  </head>
-
-  <body>
-
-    <div class="navbar navbar-fixed-top">
-      <div class="navbar-inner">
-        <div class="container">
-          <a class="brand" href="/">DevStack</a>
-          <ul class="nav pull-right">
-            <li><a href="../overview.html">Overview</a></li>
-            <li><a href="../changes.html">Changes</a></li>
-            <li><a href="../faq.html">FAQ</a></li>
-            <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
-            <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
-          </ul>
-        </div>
-      </div>
-    </div>
-
-    <div class="container">
-      <section id="overview">
-        <h1>All-In-One: Dedicated Hardware</h1>
-        <p>Things are about to get real!  Using OpenStack in containers or VMs is nice for kicking the tires, but doesn't compare to the feeling you get with hardware.</p>
-      </section>
-
-      <section id="prerequisites">
-        <div class="page-header">
-          <h2>Prerequisites <small>Linux & Network</small></h2>
-        </div>
-        
-        <h3>Minimal Install</h3>
-        <p>You need to have a system with a fresh install of Linux.  You can download the <a href="https://help.ubuntu.com/community/Installation/MinimalCD">Minimal CD</a> for Ubuntu releases since DevStack will download &amp; install all the additional dependencies.  The netinstall ISO is available for <a href="http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso">Fedora</a> and <a href="http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso">CentOS/RHEL</a>.  You may be tempted to use a desktop distro on a laptop, it will probably work but you may need to tell Network Manager to keep its fingers off the interface(s) that OpenStack uses for bridging.</p>
-        
-        <h3>Network Configuration</h3>
-        <p>Determine the network configuration on the interface used to integrate your 
-        OpenStack cloud with your existing network. For example, if the IPs given out on your network 
-        by DHCP are 192.168.1.X - where X is between 100 and 200 you will be able to use IPs 
-        201-254 for <b>floating ips</b>.</p>
-        <p>To make things easier later change your host to use a static IP instead of DHCP (i.e. 192.168.1.201).</p>
-      </section>
-
-      <section id="installation">
-        <div class="page-header">
-          <h2>Installation <small>shake and bake</small></h2>
-        </div>
-
-        <h3>Add your user</h3>
-        <p>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)</p>
-        <pre>adduser stack</pre>
-        <p>Since this user will be making many changes to your system, it will need to have sudo privileges:</p>
-        <pre>apt-get install sudo -y || yum install -y sudo
-echo "stack ALL=(ALL) NOPASSWD: ALL" &gt;&gt; /etc/sudoers</pre>
-        <p>From here on you should use the user you created.  <b>Logout</b> and <b>login</b> as that user.</p>
-
-        <h3>Download DevStack</h3>
-        <p>We'll grab the latest version of DevStack via https:</p>
-        <pre>sudo apt-get install git -y || yum install -y git
-git clone https://git.openstack.org/openstack-dev/devstack
-cd devstack</pre>
-
-        <h3>Run DevStack</h3>
-        <p>Now to configure <code>stack.sh</code>.  DevStack includes a sample in <code>devstack/samples/local.conf</code>.  Create <code>local.conf</code> as shown below to do the following:</p>
-        <ul>
-          <li>Set <code>FLOATING_RANGE</code> to a range not used on the local network, i.e. 192.168.1.224/27.  This configures IP addresses ending in 225-254 to be used as floating IPs.</li>
-          <li>Set <code>FIXED_RANGE</code> and <code>FIXED_NETWORK_SIZE</code> to configure the internal address space used by the instances.</li>
-          <li>Set <code>FLAT_INTERFACE</code> to the Ethernet interface that connects the host to your local network.  This is the interface that should be configured with the static IP address mentioned above.</li>
-          <li>Set the administrative password.  This password is used for the <b>admin</b> and <b>demo</b> accounts set up as OpenStack users.</li>
-          <li>Set the MySQL administrative password.  The default here is a random hex string which is inconvenient if you need to look at the database directly for anything.</li>
-          <li>Set the RabbitMQ password.</li>
-          <li>Set the service password.  This is used by the OpenStack services (Nova, Glance, etc) to authenticate with Keystone.</li>
-        </ul>
-        <p><code>local.conf</code> should look something like this:</p>
-        <pre>[[local|localrc]]
-FLOATING_RANGE=192.168.1.224/27
-FIXED_RANGE=10.11.12.0/24
-FIXED_NETWORK_SIZE=256
-FLAT_INTERFACE=eth0
-ADMIN_PASSWORD=supersecret
-MYSQL_PASSWORD=iheartdatabases
-RABBIT_PASSWORD=flopsymopsy
-SERVICE_PASSWORD=iheartksl</pre>
-
-        <p>Run DevStack:</p>
-        <pre>./stack.sh</pre>
-        <p>A seemingly endless stream of activity ensues.  When complete you will see a summary of
-        <code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
-        shiny new OpenStack.</p>
-
-        <h3>Using OpenStack</h3>
-        <p>At this point you should be able to access the dashboard from other computers on the 
-        local network.  In this example that would be http://192.168.1.201/ for the dashboard (aka Horizon).
-        Launch VMs and if you give them floating IPs and security group access those VMs will be accessible from other machines on your network.</p>
-
-        <p>Some examples of using the OpenStack command-line clients <code>nova</code> and <code>glance</code>
-        are in the shakedown scripts in <code>devstack/exercises</code>.  <code>exercise.sh</code>
-        will run all of those scripts and report on the results.</p>
-
-      </section>
-
-      <footer>
-        <p>&copy; Openstack Foundation 2011-2013 &mdash; An <a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a> created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
-      </footer>
-
-    </div> <!-- /container -->
-
-  </body>
-</html>
diff --git a/doc/source/guides/single-machine.rst b/doc/source/guides/single-machine.rst
new file mode 100644
index 0000000..0db0466
--- /dev/null
+++ b/doc/source/guides/single-machine.rst
@@ -0,0 +1,145 @@
+`DevStack </>`__
+
+-  `Overview <../overview.html>`__
+-  `Changes <../changes.html>`__
+-  `FAQ <../faq.html>`__
+-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
+-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+
+All-In-One: Dedicated Hardware
+==============================
+
+Things are about to get real! Using OpenStack in containers or VMs is
+nice for kicking the tires, but doesn't compare to the feeling you get
+with hardware.
+
+Prerequisites Linux & Network
+-----------------------------
+
+Minimal Install
+~~~~~~~~~~~~~~~
+
+You need to have a system with a fresh install of Linux. You can
+download the `Minimal
+CD <https://help.ubuntu.com/community/Installation/MinimalCD>`__ for
+Ubuntu releases since DevStack will download & install all the
+additional dependencies. The netinstall ISO is available for
+`Fedora <http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso>`__
+and
+`CentOS/RHEL <http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso>`__.
+You may be tempted to use a desktop distro on a laptop, it will probably
+work but you may need to tell Network Manager to keep its fingers off
+the interface(s) that OpenStack uses for bridging.
+
+Network Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+Determine the network configuration on the interface used to integrate
+your OpenStack cloud with your existing network. For example, if the IPs
+given out on your network by DHCP are 192.168.1.X - where X is between
+100 and 200 you will be able to use IPs 201-254 for **floating ips**.
+
+To make things easier later change your host to use a static IP instead
+of DHCP (i.e. 192.168.1.201).
+
+Installation shake and bake
+---------------------------
+
+Add your user
+~~~~~~~~~~~~~
+
+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)
+
+::
+
+    adduser stack
+
+Since this user will be making many changes to your system, it will need
+to have sudo privileges:
+
+::
+
+    apt-get install sudo -y || yum install -y sudo
+    echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+From here on you should use the user you created. **Logout** and
+**login** as that user.
+
+Download DevStack
+~~~~~~~~~~~~~~~~~
+
+We'll grab the latest version of DevStack via https:
+
+::
+
+    sudo apt-get install git -y || yum install -y git
+    git clone https://git.openstack.org/openstack-dev/devstack
+    cd devstack
+
+Run DevStack
+~~~~~~~~~~~~
+
+Now to configure ``stack.sh``. DevStack includes a sample in
+``devstack/samples/local.conf``. Create ``local.conf`` as shown below to
+do the following:
+
+-  Set ``FLOATING_RANGE`` to a range not used on the local network, i.e.
+   192.168.1.224/27. This configures IP addresses ending in 225-254 to
+   be used as floating IPs.
+-  Set ``FIXED_RANGE`` and ``FIXED_NETWORK_SIZE`` to configure the
+   internal address space used by the instances.
+-  Set ``FLAT_INTERFACE`` to the Ethernet interface that connects the
+   host to your local network. This is the interface that should be
+   configured with the static IP address mentioned above.
+-  Set the administrative password. This password is used for the
+   **admin** and **demo** accounts set up as OpenStack users.
+-  Set the MySQL administrative password. The default here is a random
+   hex string which is inconvenient if you need to look at the database
+   directly for anything.
+-  Set the RabbitMQ password.
+-  Set the service password. This is used by the OpenStack services
+   (Nova, Glance, etc) to authenticate with Keystone.
+
+``local.conf`` should look something like this:
+
+::
+
+    [[local|localrc]]
+    FLOATING_RANGE=192.168.1.224/27
+    FIXED_RANGE=10.11.12.0/24
+    FIXED_NETWORK_SIZE=256
+    FLAT_INTERFACE=eth0
+    ADMIN_PASSWORD=supersecret
+    MYSQL_PASSWORD=iheartdatabases
+    RABBIT_PASSWORD=flopsymopsy
+    SERVICE_PASSWORD=iheartksl
+
+Run DevStack:
+
+::
+
+    ./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,
+accounts and passwords to poke at your shiny new OpenStack.
+
+Using OpenStack
+~~~~~~~~~~~~~~~
+
+At this point you should be able to access the dashboard from other
+computers on the local network. In this example that would be
+http://192.168.1.201/ for the dashboard (aka Horizon). Launch VMs and if
+you give them floating IPs and security group access those VMs will be
+accessible from other machines on your network.
+
+Some examples of using the OpenStack command-line clients ``nova`` and
+``glance`` are in the shakedown scripts in ``devstack/exercises``.
+``exercise.sh`` will run all of those scripts and report on the results.
+
+© Openstack Foundation 2011-2013 — An `OpenStack
+program <https://wiki.openstack.org/wiki/Programs>`__ created by
+`Rackspace Cloud
+Builders <http://www.rackspace.com/cloud/private_edition/>`__
diff --git a/doc/source/guides/single-vm.html b/doc/source/guides/single-vm.html
deleted file mode 100644
index d189319..0000000
--- a/doc/source/guides/single-vm.html
+++ /dev/null
@@ -1,137 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <title>Single Machine Guide - DevStack</title>
-    <meta name="description" content="">
-    <meta name="author" content="">
-
-    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
-    <!--[if lt IE 9]>
-      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
-    <![endif]-->
-
-    <!-- Le styles -->
-    <link href="../assets/css/bootstrap.css" rel="stylesheet">
-    <link href="../assets/css/local.css" rel="stylesheet">
-    <style type="text/css">
-      body { padding-top: 60px; }
-      dd { padding: 10px; }
-    </style>
-    
-    <!-- Le javascripts -->
-    <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
-    <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
-  </head>
-
-  <body>
-
-    <div class="navbar navbar-fixed-top">
-      <div class="navbar-inner">
-        <div class="container">
-          <a class="brand" href="/">DevStack</a>
-          <ul class="nav pull-right">
-            <li><a href="../overview.html">Overview</a></li>
-            <li><a href="../changes.html">Changes</a></li>
-            <li><a href="../faq.html">FAQ</a></li>
-            <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
-            <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
-          </ul>
-        </div>
-      </div>
-    </div>
-
-    <div class="container">
-      <section id="overview">
-        <h1>Running a Cloud in a VM</h1>
-        <p>Use the cloud to build the cloud! Use your cloud to launch new versions of OpenStack 
-        in about 5 minutes.  When you break it, start over!  The VMs launched in the cloud will 
-        be slow as they are running in QEMU (emulation), but their primary use is testing
-        OpenStack development and operation.  Speed not required.</p>
-      </section>
-
-      <section id="prerequisites">
-        <div class="page-header">
-          <h2>Prerequisites <small>Cloud & Image</small></h2>
-        </div>
-
-        <h3>Virtual Machine</h3>
-        <p>DevStack should run in any virtual machine running a supported Linux release.  It will perform best with 2Gb or more of RAM.</p>
-
-        <h3>OpenStack Deployment &amp; cloud-init</h3>
-        <p>If the cloud service has an image with <code>cloud-init</code> pre-installed, use it.  You can
-        get one from <a href="http://uec-images.ubuntu.com">Ubuntu's Daily Build</a>
-        site if necessary.  This will enable you to launch VMs with userdata that installs 
-        everything at boot time.  The userdata script below will install and run
-        DevStack with a minimal configuration.  The use of <code>cloud-init</code>
-        is outside the scope of this document, refer to <a href"http://cloudinit.readthedocs.org/en/latest/index.html">the
-        <code>cloud-init</code> docs</a> for more information.</p>
-
-        <p>If you are directly using a hypervisor like Xen, kvm or VirtualBox you can manually kick off
-        the script below as a non-root user in a bare-bones server installation.</p>
-      </section>
-
-      <section id="requirements">
-        <div class="page-header">
-          <h2>Installation <small>shake and bake</small></h2>
-        </div>
-
-        <h3>Launching With Cloud-Init</h3>
-        <p>This cloud config grabs the latest version of DevStack via git, creates a minimal 
-        <code>local.conf</code> file and kicks off <code>stack.sh</code>.  It should
-        be passed as the user-data file when booting the VM.</p>
-        <pre>#cloud-config
-
-users:
-  - default
-  - name: stack
-    lock_passwd: False
-    sudo: ["ALL=(ALL) NOPASSWD:ALL\nDefaults:stack !requiretty"]
-    shell: /bin/bash
-
-write_files:
-  - content: |
-        #!/bin/sh
-        DEBIAN_FRONTEND=noninteractive sudo apt-get -qqy update || sudo yum update -qy
-        DEBIAN_FRONTEND=noninteractive sudo apt-get install -qqy git || sudo yum install -qy git
-        sudo chown stack:stack /home/stack
-        cd /home/stack
-        git clone https://git.openstack.org/openstack-dev/devstack
-        cd devstack
-        echo '[[local|localrc]]' > local.conf
-        echo ADMIN_PASSWORD=password >> local.conf
-        echo MYSQL_PASSWORD=password >> local.conf
-        echo RABBIT_PASSWORD=password >> local.conf
-        echo SERVICE_PASSWORD=password >> local.conf
-        echo SERVICE_TOKEN=tokentoken >> local.conf
-        ./stack.sh
-    path: /home/stack/start.sh
-    permissions: 0755
-
-runcmd:
-  - su -l stack ./start.sh</pre>
-        <p>As DevStack will refuse to run as root, this configures <code>cloud-init</code>
-        to create a non-root user and run the <code>start.sh</code> script as that user.</p>
-
-        <h3>Launching By Hand</h3>
-        <p>Using a hypervisor directly, launch the VM and either manually perform the steps in the 
-        embedded shell script above or copy it into the VM.</p>
-
-        <h3>Using OpenStack</h3>
-        <p>At this point you should be able to access the dashboard.  Launch VMs and if you give them floating IPs access those VMs from other machines on your network.</p>
-
-        <p>One interesting use case is for developers working on a VM on their laptop.  Once
-        <code>stack.sh</code> has completed once, all of the pre-requisite packages are installed
-        in the VM and the source trees checked out.  Setting <code>OFFLINE=True</code> in
-        <code>local.conf</code> enables <code>stack.sh</code> to run multiple times without an Internet
-        connection.  DevStack, making hacking at the lake possible since 2012!</p>
-      </section>
-
-      <footer>
-        <p>&copy; Openstack Foundation 2011-2014 &mdash; An <a href="https://www.openstack.org/">OpenStack</a> <a href="https://wiki.openstack.org/wiki/Programs">program</a></p>
-      </footer>
-
-    </div> <!-- /container -->
-
-  </body>
-</html>
diff --git a/doc/source/guides/single-vm.rst b/doc/source/guides/single-vm.rst
new file mode 100644
index 0000000..0e2d157
--- /dev/null
+++ b/doc/source/guides/single-vm.rst
@@ -0,0 +1,110 @@
+`DevStack </>`__
+
+-  `Overview <../overview.html>`__
+-  `Changes <../changes.html>`__
+-  `FAQ <../faq.html>`__
+-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
+-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+
+Running a Cloud in a VM
+=======================
+
+Use the cloud to build the cloud! Use your cloud to launch new versions
+of OpenStack in about 5 minutes. When you break it, start over! The VMs
+launched in the cloud will be slow as they are running in QEMU
+(emulation), but their primary use is testing OpenStack development and
+operation. Speed not required.
+
+Prerequisites Cloud & Image
+---------------------------
+
+Virtual Machine
+~~~~~~~~~~~~~~~
+
+DevStack should run in any virtual machine running a supported Linux
+release. It will perform best with 2Gb or more of RAM.
+
+OpenStack Deployment & cloud-init
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the cloud service has an image with ``cloud-init`` pre-installed, use
+it. You can get one from `Ubuntu's Daily
+Build <http://uec-images.ubuntu.com>`__ site if necessary. This will
+enable you to launch VMs with userdata that installs everything at boot
+time. The userdata script below will install and run DevStack with a
+minimal configuration. The use of ``cloud-init`` is outside the scope of
+this document, refer to the ``cloud-init`` docs for more information.
+
+If you are directly using a hypervisor like Xen, kvm or VirtualBox you
+can manually kick off the script below as a non-root user in a
+bare-bones server installation.
+
+Installation shake and bake
+---------------------------
+
+Launching With Cloud-Init
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This cloud config grabs the latest version of DevStack via git, creates
+a minimal ``local.conf`` file and kicks off ``stack.sh``. It should be
+passed as the user-data file when booting the VM.
+
+::
+
+    #cloud-config
+
+    users:
+      - default
+      - name: stack
+        lock_passwd: False
+        sudo: ["ALL=(ALL) NOPASSWD:ALL\nDefaults:stack !requiretty"]
+        shell: /bin/bash
+
+    write_files:
+      - content: |
+            #!/bin/sh
+            DEBIAN_FRONTEND=noninteractive sudo apt-get -qqy update || sudo yum update -qy
+            DEBIAN_FRONTEND=noninteractive sudo apt-get install -qqy git || sudo yum install -qy git
+            sudo chown stack:stack /home/stack
+            cd /home/stack
+            git clone https://git.openstack.org/openstack-dev/devstack
+            cd devstack
+            echo '[[local|localrc]]' > local.conf
+            echo ADMIN_PASSWORD=password >> local.conf
+            echo MYSQL_PASSWORD=password >> local.conf
+            echo RABBIT_PASSWORD=password >> local.conf
+            echo SERVICE_PASSWORD=password >> local.conf
+            echo SERVICE_TOKEN=tokentoken >> local.conf
+            ./stack.sh
+        path: /home/stack/start.sh
+        permissions: 0755
+
+    runcmd:
+      - su -l stack ./start.sh
+
+As DevStack will refuse to run as root, this configures ``cloud-init``
+to create a non-root user and run the ``start.sh`` script as that user.
+
+Launching By Hand
+~~~~~~~~~~~~~~~~~
+
+Using a hypervisor directly, launch the VM and either manually perform
+the steps in the embedded shell script above or copy it into the VM.
+
+Using OpenStack
+~~~~~~~~~~~~~~~
+
+At this point you should be able to access the dashboard. Launch VMs and
+if you give them floating IPs access those VMs from other machines on
+your network.
+
+One interesting use case is for developers working on a VM on their
+laptop. Once ``stack.sh`` has completed once, all of the pre-requisite
+packages are installed in the VM and the source trees checked out.
+Setting ``OFFLINE=True`` in ``local.conf`` enables ``stack.sh`` to run
+multiple times without an Internet connection. DevStack, making hacking
+at the lake possible since 2012!
+
+© Openstack Foundation 2011-2014 — An
+`OpenStack <https://www.openstack.org/>`__
+`program <https://wiki.openstack.org/wiki/Programs>`__
diff --git a/doc/source/guides/usb-boot.html b/doc/source/guides/usb-boot.html
deleted file mode 100644
index 2a05f89..0000000
--- a/doc/source/guides/usb-boot.html
+++ /dev/null
@@ -1,99 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <title>USB Boot Server Guide - DevStack</title>
-    <meta name="description" content="">
-    <meta name="author" content="">
-
-    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
-    <!--[if lt IE 9]>
-      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
-    <![endif]-->
-
-    <!-- Le styles -->
-    <link href="../assets/css/bootstrap.css" rel="stylesheet">
-    <link href="../assets/css/local.css" rel="stylesheet">
-    <style type="text/css">
-      body { padding-top: 60px; }
-      dd { padding: 10px; }
-    </style>
-    
-    <!-- Le javascripts -->
-    <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
-    <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
-  </head>
-
-  <body>
-
-    <div class="navbar navbar-fixed-top">
-      <div class="navbar-inner">
-        <div class="container">
-          <a class="brand" href="/">DevStack</a>
-          <ul class="nav pull-right">
-            <li><a href="../overview.html">Overview</a></li>
-            <li><a href="../changes.html">Changes</a></li>
-            <li><a href="../faq.html">FAQ</a></li>
-            <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
-            <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
-          </ul>
-        </div>
-      </div>
-    </div>
-
-    <div class="container">
-      <section id="overview">
-        <h1>USB Boot: Undoable Stack Boot</h1>
-        <p>Boot DevStack from a USB disk into a RAM disk.</p>
-      </section>
-
-      <section id="requirements">
-        <div class="page-header">
-          <h2>Prerequisites</h2>
-        </div>
-        
-        <h3>Hardware</h3>
-        <p>This guide covers the creation of a bootable USB drive.  Your 
-           computer BIOS must support booting from USB and You will want at least 3GB of 
-           RAM.  You also will need a USB drive of at least 2GB.</p>
-
-        <h3>Software</h3>
-        <p>Ubuntu 11.10 (Oneiric Ocelot) is required on host to create images.</p>
-      </section>
-
-      <section id="installation">
-        <div class="page-header">
-          <h2>Installation <small>bit blasting</small></h2>
-        </div>
-
-        <h3>Set Up USB Drive</h3>
-        <ul>
-          <li>Insert the USB drive into the computer.  Make a note of the device name, such as 
-          <code>sdb</code>. Do not mount the device.</li>
-          <li>Install the boot system:
-            <pre>tools/build_usb_boot.sh /dev/sdb1</pre>
-            <p>This calls tools/build_ramdisk.sh to create a 2GB ramdisk 
-               containing a complete development Oneiric OS plus the 
-               OpenStack code checkouts.  It then writes a syslinux boot sector
-               to the specified device and creates <code>/syslinux</code>.</p>
-          </li>
-          <li>If desired, you may now mount the device:
-            <pre>mount /dev/sdb1 /mnt/tmp
-# foo
-umount /mnt/tmp</pre>
-          </li>
-        </ul>
-
-        <p>Now <a href="ramdisk.html">return</a> to the RAM disk Guide to kick
-           off your DevStack experience.</p>
-
-      </section>
-
-      <footer>
-        <p>&copy; Openstack Foundation 2011-2013 &mdash; this is not an official OpenStack project...</p>
-      </footer>
-
-    </div> <!-- /container -->
-
-  </body>
-</html>
diff --git a/doc/source/guides/usb-boot.rst b/doc/source/guides/usb-boot.rst
new file mode 100644
index 0000000..888e14f
--- /dev/null
+++ b/doc/source/guides/usb-boot.rst
@@ -0,0 +1,60 @@
+`DevStack </>`__
+
+-  `Overview <../overview.html>`__
+-  `Changes <../changes.html>`__
+-  `FAQ <../faq.html>`__
+-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
+-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+
+USB Boot: Undoable Stack Boot
+=============================
+
+Boot DevStack from a USB disk into a RAM disk.
+
+Prerequisites
+-------------
+
+Hardware
+~~~~~~~~
+
+This guide covers the creation of a bootable USB drive. Your computer
+BIOS must support booting from USB and You will want at least 3GB of
+RAM. You also will need a USB drive of at least 2GB.
+
+Software
+~~~~~~~~
+
+Ubuntu 11.10 (Oneiric Ocelot) is required on host to create images.
+
+Installation bit blasting
+-------------------------
+
+Set Up USB Drive
+~~~~~~~~~~~~~~~~
+
+-  Insert the USB drive into the computer. Make a note of the device
+   name, such as ``sdb``. Do not mount the device.
+-  Install the boot system:
+
+   ::
+
+       tools/build_usb_boot.sh /dev/sdb1
+
+   This calls tools/build\_ramdisk.sh to create a 2GB ramdisk containing
+   a complete development Oneiric OS plus the OpenStack code checkouts.
+   It then writes a syslinux boot sector to the specified device and
+   creates ``/syslinux``.
+
+-  If desired, you may now mount the device:
+
+   ::
+
+       mount /dev/sdb1 /mnt/tmp
+       # foo
+       umount /mnt/tmp
+
+Now `return <ramdisk.html>`__ to the RAM disk Guide to kick off your
+DevStack experience.
+
+© Openstack Foundation 2011-2013 — this is not an official OpenStack
+project...