WIP

docs/README.rst

@@ -1,10 +1,14 @@
+Faucet Documentation
+====================
+
+
 Viewing documentation
-=====================
+---------------------
 
 Docs are viewable on `readthedocs <https://faucet.readthedocs.io>`_.
 
 Building documentation
-======================
+----------------------
 
 .. code:: bash
 

vm/README.md → vm/README.rst

@@ -1,28 +1,34 @@
+Faucet VM
+=========
+
 We provide a VM image for running FAUCET for development and learning purposes.
 The VM comes pre-installed with FAUCET, GAUGE, prometheus and grafana.
 
-Openstack's [diskimage-builder](https://docs.openstack.org/diskimage-builder/latest/) (DIB)
-is used to build the VM images in many formats (qcow2,tgz,squashfs,vhd,raw).
+Openstack's `diskimage-builder <https://docs.openstack.org/diskimage-builder/latest/>`_
+(DIB) is used to build the VM images in many formats (qcow2,tgz,squashfs,vhd,raw).
 
-We provide [DIB elements](elements) for configuring each component installed in the VM.
+We provide `DIB elements <elements>`_ for configuring each component installed in the VM.
 
-Pre-built images are available on our build host [https://builder.faucet.nz](https://builder.faucet.nz).
+Pre-built images are available on our build host `<https://builder.faucet.nz>`_.
 
-## Building the images
+Building the images
+-------------------
 
-If you don't want to use our [pre-built images](https://builder.faucet.nz), you can build them yourself:
+If you don't want to use our `pre-built images <https://builder.faucet.nz>`_, you can build them yourself:
 
-1. [Install the latest disk-image-builder](https://docs.openstack.org/diskimage-builder/latest/user_guide/installation.html)
-2. [Install a patched vhd-util](https://launchpad.net/~openstack-ci-core/+archive/ubuntu/vhd-util)
+1. `Install the latest disk-image-builder <https://docs.openstack.org/diskimage-builder/latest/user_guide/installation.html>`_
+2. `Install a patched vhd-util <https://launchpad.net/~openstack-ci-core/+archive/ubuntu/vhd-util>`_
 3. Run build-faucet-vm.sh
 
-## Security Considerations
+Security Considerations
+-----------------------
 
 This VM is not secure by default, it includes no firewall and has a number of
 network services listening on all interfaces with weak passwords. It also
 includes a backdoor user (faucet) with weak credentials.
 
-## Services
+Services
+--------
 
 The VM exposes a number of ports listening on all interfaces by default:
 
@@ -42,18 +48,19 @@ The VM exposes a number of ports listening on all interfaces by default:
 | SSH                      | faucet   | faucet   |
 | Grafana Web Interface    | admin    | admin    |
 
-## Post-Install Steps
+Post-Install Steps
+------------------
 
 Grafana comes installed but unconfigured, you will need to login to the grafana
-web interface at http://VM_IP:3000 and configure a data source and some dashboards.
+web interface at ``http://VM_IP:3000`` and configure a data source and some dashboards.
 
-After logging in with the default credentials shown above, the first step is to add a [prometheus data source](https://prometheus.io/docs/visualization/grafana/#creating-a-prometheus-data-source),
-please add "http://localhost:9090" as your data source.
-Next step is to configure some dashboards, you can add some we have [prepared earlier](https://monitoring.redcables.wand.nz/grafana-dashboards/)
-or [create your own](http://docs.grafana.org/features/datasources/prometheus/).
+After logging in with the default credentials shown above, the first step is to add a `prometheus data source <https://prometheus.io/docs/visualization/grafana/#creating-a-prometheus-data-source>`_,
+please add ``http://localhost:9090`` as your data source.
+Next step is to configure some dashboards, you can add some we have `prepared earlier <https://monitoring.redcables.wand.nz/grafana-dashboards/>`_
+or `create your own <http://docs.grafana.org/features/datasources/prometheus/>`_.
 
 You will need to supply your own faucet.yaml and gauge.yaml configuration in the VM.
 There are samples provided at /etc/ryu/faucet/faucet.yaml and /etc/ryu/faucet/gauge.yaml.
 
 Finally you will need to point one of the supported OpenFlow vendors at the controller VM,
-port 6653 is the FAUCET OpenFlow control channel and 6654 is the GAUGE OpennFlow control channel for monitoring.
+port 6653 is the Faucet OpenFlow control channel and 6654 is the Gauge OpennFlow control channel for monitoring.