doc: Convert third-party/README to rST

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Russell Bryant <russell@ovn.org>

3 files changed, 67 insertions, 39 deletions

diff --git a/third-party/README.md b/third-party/README.md
deleted file mode 100644
index d351d77e5..000000000
--- a/third-party/README.md
+++ /dev/null
@@ -1,38 +0,0 @@
-Third-party software integration
-================================
-
-This directory contains third-party software that may be useful for
-debugging.
-
-tcpdump
--------
-The "ofp-tcpdump.patch" patch adds the ability to parse OpenFlow
-messages to tcpdump.  These instructions assume that tcpdump 4.3.0
-is going to be used, but it should work with other versions that are not
-substantially different.  To begin, download tcpdump and apply the
-patch:
-
-    wget http://www.tcpdump.org/release/tcpdump-4.3.0.tar.gz
-    tar xzf tcpdump-4.3.0.tar.gz
-    ln -s tcpdump-4.3.0 tcpdump
-    patch -p0 < ofp-tcpdump.patch
-
-Then build the new version of tcpdump:
-
-    cd tcpdump
-    ./configure
-    make
-
-Clearly, tcpdump can only parse unencrypted packets, so you will need to
-connect the controller and datapath using plain TCP.  To look at the
-traffic, tcpdump will be started in a manner similar to the following:
-
-    sudo ./tcpdump -s0 -i eth0 port 6653
-
-The "-s0" flag indicates that tcpdump should capture the entire packet.
-If the OpenFlow message is not received in its entirety, "[|openflow]" will 
-be printed instead of the OpenFlow message contents.
-
-The verbosity of the output may be increased by adding additional "-v"
-flags.  If "-vvv" is used, the raw OpenFlow data is also printed in
-hex and ASCII.
diff --git a/third-party/README.rst b/third-party/README.rst
new file mode 100644
index 000000000..9d536c306
--- /dev/null
+++ b/third-party/README.rst
@@ -0,0 +1,66 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+================================
+Third-party software integration
+================================
+
+This directory contains third-party software that may be useful for debugging.
+
+tcpdump
+-------
+
+The ``ofp-tcpdump.patch`` patch adds the ability to parse OpenFlow messages to
+tcpdump.  These instructions assume that tcpdump 4.3.0 is going to be used, but
+it should work with other versions that are not substantially different.  To
+begin, download tcpdump and apply the patch:
+
+::
+
+    $ wget http://www.tcpdump.org/release/tcpdump-4.3.0.tar.gz
+    $ tar xzf tcpdump-4.3.0.tar.gz
+    $ ln -s tcpdump-4.3.0 tcpdump
+    $ patch -p0 < ofp-tcpdump.patch
+
+Then build the new version of tcpdump:
+
+::
+
+    $ cd tcpdump
+    $ ./configure
+    $ make
+
+Clearly, tcpdump can only parse unencrypted packets, so you will need to
+connect the controller and datapath using plain TCP.  To look at the traffic,
+tcpdump will be started in a manner similar to the following:
+
+::
+
+    $ sudo ./tcpdump -s0 -i eth0 port 6653
+
+The ``-s0`` flag indicates that tcpdump should capture the entire packet.  If
+the OpenFlow message is not received in its entirety, ``[|openflow]`` will be
+printed instead of the OpenFlow message contents.
+
+The verbosity of the output may be increased by adding additional ``-v`` flags.
+If ``-vvv`` is used, the raw OpenFlow data is also printed in hex and ASCII.
diff --git a/third-party/automake.mk b/third-party/automake.mk
index fea5ac763..9eaf02f81 100644
--- a/third-party/automake.mk
+++ b/third-party/automake.mk
@@ -1,2 +1,2 @@
-docs += third-party/README.md
+docs += third-party/README.rst
 EXTRA_DIST += third-party/ofp-tcpdump.patch