[ovs-dev] [PATCH 4/9] doc: Convert INSTALL.Debian to rST

Stephen Finucane stephen at that.guru
Sat Oct 8 16:30:26 UTC 2016


Signed-off-by: Stephen Finucane <stephen at that.guru>
---
 INSTALL.Debian.md       | 101 -----------------------------------------
 INSTALL.Debian.rst      | 117 ++++++++++++++++++++++++++++++++++++++++++++++++
 INSTALL.rst             |   2 +-
 Makefile.am             |   2 +-
 README.md               |   4 +-
 vtep/README.ovs-vtep.md |   2 +-
 6 files changed, 122 insertions(+), 106 deletions(-)
 delete mode 100644 INSTALL.Debian.md
 create mode 100644 INSTALL.Debian.rst

diff --git a/INSTALL.Debian.md b/INSTALL.Debian.md
deleted file mode 100644
index e8a6392..0000000
--- a/INSTALL.Debian.md
+++ /dev/null
@@ -1,101 +0,0 @@
-How to Build Debian Packages for Open vSwitch
-=============================================
-
-This document describes how to build Debian packages for Open vSwitch.
-To install Open vSwitch on Debian without building Debian packages,
-see [INSTALL.rst] instead.
-
-These instructions should also work on Ubuntu and other Debian
-derivative distributions.
-
-
-Before You Begin
-----------------
-
-Before you begin, consider whether you really need to build packages
-yourself.  Debian "wheezy" and "sid", as well as recent versions of
-Ubuntu, contain pre-built Debian packages for Open vSwitch.  It is
-easier to install these than to build your own.  To use packages from
-your distribution, skip ahead to "Installing .deb Packages", below.
-
-
-Building Open vSwitch Debian packages
--------------------------------------
-
-You may build from an Open vSwitch distribution tarball or from an
-Open vSwitch Git tree with these instructions.
-
-You do not need to be the superuser to build the Debian packages.
-
-1. Install the "build-essential" and "fakeroot" packages, e.g. with
-   `apt-get install build-essential fakeroot`.
-
-2. Obtain and unpack an Open vSwitch source distribution and `cd` into
-   its top level directory.
-
-3. Install the build dependencies listed under "Build-Depends:" near
-   the top of debian/control.  You can install these any way you like,
-   e.g. with `apt-get install`.
-
-   Check your work by running `dpkg-checkbuilddeps` in the top level of
-   your ovs directory.  If you've installed all the dependencies
-   properly, dpkg-checkbuilddeps will exit without printing anything.
-   If you forgot to install some dependencies, it will tell you which ones.
-
-4. Run:
-
-       `fakeroot debian/rules binary`
-
-   This will do a serial build that runs the unit tests. This will take
-   approximately 8 to 10 minutes. If you prefer, you can run a faster
-   parallel build, e.g.:
-
-       `DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary`
-
-   If you are in a big hurry, you can even skip the unit tests:
-
-       `DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary`
-
-   (There are a few pitfalls in the Debian packaging building system
-   so that, occasionally, you may find that in a tree that you have
-   using for a while, the build command above exits immediately
-   without actually building anything.  To fix the problem, run
-
-       `fakeroot debian/rules clean`
-
-   or start over from a fresh copy of the source tree.)
-
-5. The generated .deb files will be in the parent directory of the
-   Open vSwitch source distribution.
-
-
-Installing .deb Packages
-------------------------
-
-These instructions apply to installing from Debian packages that you
-built yourself, as described in the previous section, or from packages
-provided by Debian or a Debian derivative distribution such as Ubuntu.
-In the former case, use a command such as `dpkg -i` to install the
-.deb files that you build, and in the latter case use a program such
-as `apt-get` or `aptitude` to download and install the provided
-packages.
-
-You must be superuser to install Debian packages.
-
-1. Start by installing an Open vSwitch kernel module.  See
-   debian/openvswitch-switch.README.Debian for the available options.
-
-2. Install the "openvswitch-switch" and "openvswitch-common" packages.
-   These packages include the core userspace components of the switch.
-
-Open vSwitch .deb packages not mentioned above are rarely useful.
-Please refer to their individual package descriptions to find out
-whether any of them are useful to you.
-
-
-Bug Reporting
--------------
-
-Please report problems to bugs at openvswitch.org.
-
-[INSTALL.rst]:INSTALL.rst
diff --git a/INSTALL.Debian.rst b/INSTALL.Debian.rst
new file mode 100644
index 0000000..a073158
--- /dev/null
+++ b/INSTALL.Debian.rst
@@ -0,0 +1,117 @@
+..
+      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.
+
+Building Debian Packages for Open vSwitch
+=========================================
+
+This document describes how to build Debian packages for Open vSwitch. To
+install Open vSwitch on Debian without building Debian packages, see the
+`installation guide <INSTALL.rst>`__ instead.
+
+.. note::
+  These instructions should also work on Ubuntu and other Debian derivative
+  distributions.
+
+Before You Begin
+----------------
+
+Before you begin, consider whether you really need to build packages yourself.
+Debian "wheezy" and "sid", as well as recent versions of Ubuntu, contain
+pre-built Debian packages for Open vSwitch. It is easier to install these than
+to build your own. To use packages from your distribution, skip ahead to
+"Installing .deb Packages", below.
+
+Building Open vSwitch Debian packages
+-------------------------------------
+
+You may build from an Open vSwitch distribution tarball or from an Open vSwitch
+Git tree with these instructions.
+
+You do not need to be the superuser to build the Debian packages.
+
+1. Install the "build-essential" and "fakeroot" packages. For example:::
+
+       $ apt-get install build-essential fakeroot
+
+2. Obtain and unpack an Open vSwitch source distribution and ``cd`` into its
+   top level directory.
+
+3. Install the build dependencies listed under "Build-Depends:" near the top of
+   ``debian/control``. You can install these any way you like, e.g.  with
+   ``apt-get install``.
+
+Check your work by running ``dpkg-checkbuilddeps`` in the top level of your ovs
+directory. If you've installed all the dependencies properly,
+``dpkg-checkbuilddeps`` will exit without printing anything. If you forgot to
+install some dependencies, it will tell you which ones.
+
+4. Build the package:::
+
+       $ fakeroot debian/rules binary
+
+   This will do a serial build that runs the unit tests. This will take
+   approximately 8 to 10 minutes. If you prefer, you can run a faster parallel
+   build:::
+
+       $ DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary
+
+   If you are in a big hurry, you can even skip the unit tests:::
+
+       $ DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary
+
+.. note::
+
+  There are a few pitfalls in the Debian packaging building system so that,
+  occasionally, you may find that in a tree that you have using for a while,
+  the build command above exits immediately without actually building anything.
+  To fix the problem, run:::
+
+      $ fakeroot debian/rules clean
+
+  or start over from a fresh copy of the source tree.
+
+5. The generated .deb files will be in the parent directory of the Open vSwitch
+   source distribution.
+
+Installing .deb Packages
+------------------------
+
+These instructions apply to installing from Debian packages that you built
+yourself, as described in the previous section, or from packages provided by
+Debian or a Debian derivative distribution such as Ubuntu.  In the former case,
+use a command such as ``dpkg -i`` to install the .deb files that you build, and
+in the latter case use a program such as ``apt-get`` or ``aptitude`` to
+download and install the provided packages.
+
+.. important::
+  You must be superuser to install Debian packages.
+
+1. Start by installing an Open vSwitch kernel module. See
+   ``debian/openvswitch-switch.README.Debian`` for the available options.
+
+2. Install the ``openvswitch-switch`` and ``openvswitch-common`` packages.
+   These packages include the core userspace components of the switch.
+
+Open vSwitch ``.deb`` packages not mentioned above are rarely useful. Refer to
+their individual package descriptions to find out whether any of them are
+useful to you.
diff --git a/INSTALL.rst b/INSTALL.rst
index 2093d84..612b36d 100644
--- a/INSTALL.rst
+++ b/INSTALL.rst
@@ -29,7 +29,7 @@ This document describes how to build and install Open vSwitch on a generic
 Linux, FreeBSD, or NetBSD host. For specifics around installation on a specific
 platform, refer to one of these installation guides:
 
-- `Debian <INSTALL.Debian.md>`__
+- `Debian <INSTALL.Debian.rst>`__
 - `Fedora <INSTALL.Fedora.md>`__
 - `RHEL <INSTALL.RHEL.md>`__
 - `XenServer <INSTALL.XenServer.md>`__
diff --git a/Makefile.am b/Makefile.am
index f10d552..4cd5ece 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -71,7 +71,7 @@ docs = \
 	DESIGN.md \
 	FAQ.md \
 	INSTALL.rst \
-	INSTALL.Debian.md \
+	INSTALL.Debian.rst \
 	INSTALL.Docker.md \
 	INSTALL.DPDK-ADVANCED.md \
 	INSTALL.DPDK.rst \
diff --git a/README.md b/README.md
index 2f79833..ff23ee9 100644
--- a/README.md
+++ b/README.md
@@ -79,7 +79,7 @@ To install Open vSwitch on a regular Linux or FreeBSD host, please
 read [INSTALL.rst]. For specifics around installation on a specific
 platform, please see one of these files:
 
-- [INSTALL.Debian.md]
+- [INSTALL.Debian.rst]
 - [INSTALL.Fedora.md]
 - [INSTALL.RHEL.md]
 - [INSTALL.XenServer.md]
@@ -116,7 +116,7 @@ Contact
 bugs at openvswitch.org
 
 [INSTALL.rst]:INSTALL.rst
-[INSTALL.Debian.md]:INSTALL.Debian.md
+[INSTALL.Debian.rst]:INSTALL.Debian.rst
 [INSTALL.Docker.md]:INSTALL.Docker.md
 [INSTALL.DPDK.rst]:INSTALL.DPDK.rst
 [INSTALL.Fedora.md]:INSTALL.Fedora.md
diff --git a/vtep/README.ovs-vtep.md b/vtep/README.ovs-vtep.md
index 13d4e1d..e08c8e6 100644
--- a/vtep/README.ovs-vtep.md
+++ b/vtep/README.ovs-vtep.md
@@ -15,7 +15,7 @@ can be done by either of the following methods.
 1. Follow the instructions in the INSTALL.md file of the Open vSwitch repository
 (don't start any daemons yet).
 
-2. Follow the instructions in INSTALL.Debian.md file and then install the
+2. Follow the instructions in INSTALL.Debian.rst file and then install the
 "openvswitch-vtep" package (if operating on a debian based machine). This
 will automatically start the daemons.
 
-- 
2.7.4




More information about the dev mailing list