[ovs-dev] [RFC 5/5] doc: Convert README to rST

Stephen Finucane stephen at that.guru
Sat Oct 1 19:01:34 UTC 2016


This is a top-level document, so plain old rST is preferred.

Signed-off-by: Stephen Finucane <stephen at that.guru>
---
This is the first time we completely replace a Markdown file with its
reStructuredText equivalent. How will this affect the 'dist-docs'
target?
---
 Documentation/install-guide/general.rst |   2 +-
 INSTALL.md                              |   4 +-
 Makefile.am                             |   2 +-
 README.md                               | 131 --------------------------------
 README.rst                              | 115 ++++++++++++++++++++++++++++
 rhel/openvswitch-fedora.spec.in         |   2 +-
 rhel/openvswitch.spec.in                |   2 +-
 utilities/ovs-ctl.8                     |   2 +-
 8 files changed, 122 insertions(+), 138 deletions(-)
 delete mode 100644 README.md
 create mode 100644 README.rst

diff --git a/Documentation/install-guide/general.rst b/Documentation/install-guide/general.rst
index e003563..cd3c4d5 100644
--- a/Documentation/install-guide/general.rst
+++ b/Documentation/install-guide/general.rst
@@ -86,7 +86,7 @@ details).
 To compile the kernel module on Linux, you must also install the
 following:
 
-- A supported Linux kernel version. Refer to the `README <../../README.md>`__
+- A supported Linux kernel version. Refer to the `README <../../README.rst>`__
   for a list of supported versions.
 
   For optional support of ingress policing, you must enable kernel
diff --git a/INSTALL.md b/INSTALL.md
index 36ecfb8..59cf762 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -60,7 +60,7 @@ at some cost in features and performance (see [INSTALL.userspace.md]
 for details).  To compile the kernel module on Linux, you must also
 install the following:
 
-  - A supported Linux kernel version.  Please refer to [README.md] for a
+  - A supported Linux kernel version.  Please refer to [README] for a
     list of supported versions.
 
     For optional support of ingress policing, you must enable kernel
@@ -811,7 +811,7 @@ Bug Reporting
 
 Please report problems to bugs at openvswitch.org.
 
-[README.md]:README.md
+[README]:README.rst
 [INSTALL.Debian.md]:INSTALL.Debian.md
 [INSTALL.Fedora.md]:INSTALL.Fedora.md
 [INSTALL.RHEL.md]:INSTALL.RHEL.md
diff --git a/Makefile.am b/Makefile.am
index 724a893..e05b1b1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -89,7 +89,7 @@ docs = \
 	MAINTAINERS.md \
 	OPENFLOW-1.1+.md \
 	PORTING.md \
-	README.md \
+	README.rst \
 	README-lisp.md \
 	README-native-tunneling.md \
 	REPORTING-BUGS.md \
diff --git a/README.md b/README.md
deleted file mode 100644
index 53b0faf..0000000
--- a/README.md
+++ /dev/null
@@ -1,131 +0,0 @@
-Open vSwitch
-============
-
-Build Status:
--------------
-
-[![Build Status](https://travis-ci.org/openvswitch/ovs.png)](https://travis-ci.org/openvswitch/ovs)
-
-What is Open vSwitch?
----------------------
-
-Open vSwitch is a multilayer software switch licensed under the open
-source Apache 2 license.  Our goal is to implement a production
-quality switch platform that supports standard management interfaces
-and opens the forwarding functions to programmatic extension and
-control.
-
-Open vSwitch is well suited to function as a virtual switch in VM
-environments.  In addition to exposing standard control and visibility
-interfaces to the virtual networking layer, it was designed to support
-distribution across multiple physical servers.  Open vSwitch supports
-multiple Linux-based virtualization technologies including
-Xen/XenServer, KVM, and VirtualBox.
-
-The bulk of the code is written in platform-independent C and is
-easily ported to other environments.  The current release of Open
-vSwitch supports the following features:
-
-* Standard 802.1Q VLAN model with trunk and access ports
-* NIC bonding with or without LACP on upstream switch
-* NetFlow, sFlow(R), and mirroring for increased visibility
-* QoS (Quality of Service) configuration, plus policing
-* Geneve, GRE, VXLAN, STT, and LISP tunneling
-* 802.1ag connectivity fault management
-* OpenFlow 1.0 plus numerous extensions
-* Transactional configuration database with C and Python bindings
-* High-performance forwarding using a Linux kernel module
-
-The included Linux kernel module supports Linux 3.10 and up.
-
-Open vSwitch can also operate, at a cost in performance, entirely in
-userspace, without assistance from a kernel module.  This userspace
-implementation should be easier to port than the kernel-based switch.
-It is considered experimental.
-
-What's here?
-------------
-
-The main components of this distribution are:
-
-* ovs-vswitchd, a daemon that implements the switch, along with
-  a companion Linux kernel module for flow-based switching.
-* ovsdb-server, a lightweight database server that ovs-vswitchd
-  queries to obtain its configuration.
-* ovs-dpctl, a tool for configuring the switch kernel module.
-* Scripts and specs for building RPMs for Citrix XenServer and Red
-  Hat Enterprise Linux.  The XenServer RPMs allow Open vSwitch to
-  be installed on a Citrix XenServer host as a drop-in replacement
-  for its switch, with additional functionality.
-* ovs-vsctl, a utility for querying and updating the configuration
-  of ovs-vswitchd.
-* ovs-appctl, a utility that sends commands to running Open
-      vSwitch daemons.
-
-Open vSwitch also provides some tools:
-
-* ovs-ofctl, a utility for querying and controlling OpenFlow
-  switches and controllers.
-* ovs-pki, a utility for creating and managing the public-key
-  infrastructure for OpenFlow switches.
-* ovs-testcontroller, a simple OpenFlow controller that may be useful
-  for testing (though not for production).
-* A patch to tcpdump that enables it to parse OpenFlow messages.
-
-What other documentation is available?
---------------------------------------
-
-To install Open vSwitch on a regular Linux or FreeBSD host, please
-read [INSTALL.md]. For specifics around installation on a specific
-platform, please see one of these files:
-
-- [INSTALL.Debian.md]
-- [INSTALL.Fedora.md]
-- [INSTALL.RHEL.md]
-- [INSTALL.XenServer.md]
-
-To use Open vSwitch...
-
-- ...with Docker on Linux, read [INSTALL.Docker.md]
-
-- ...with KVM on Linux, read [INSTALL.md], read [INSTALL.KVM.md]
-
-- ...with Libvirt, read [INSTALL.Libvirt.md].
-
-- ...without using a kernel module, read [INSTALL.userspace.md].
-
-- ...with DPDK, read [INSTALL.DPDK.md].
-
-- ...with SELinux, read [INSTALL.SELinux.md].
-
-For answers to common questions, read [FAQ.md].
-
-To learn how to set up SSL support for Open vSwitch, read [INSTALL.SSL.md].
-
-To learn about some advanced features of the Open vSwitch software
-switch, read the [tutorial/Tutorial.md].
-
-Each Open vSwitch userspace program is accompanied by a manpage.  Many
-of the manpages are customized to your configuration as part of the
-build process, so we recommend building Open vSwitch before reading
-the manpages.
-
-Contact
--------
-
-bugs at openvswitch.org
-
-[INSTALL.md]:INSTALL.md
-[INSTALL.Debian.md]:INSTALL.Debian.md
-[INSTALL.Docker.md]:INSTALL.Docker.md
-[INSTALL.DPDK.md]:INSTALL.DPDK.md
-[INSTALL.Fedora.md]:INSTALL.Fedora.md
-[INSTALL.KVM.md]:INSTALL.KVM.md
-[INSTALL.Libvirt.md]:INSTALL.Libvirt.md
-[INSTALL.RHEL.md]:INSTALL.RHEL.md
-[INSTALL.SELinux.md]:INSTALL.SELinux.md
-[INSTALL.SSL.md]:INSTALL.SSL.md
-[INSTALL.userspace.md]:INSTALL.userspace.md
-[INSTALL.XenServer.md]:INSTALL.XenServer.md
-[FAQ.md]:FAQ.md
-[tutorial/Tutorial.md]:tutorial/Tutorial.md
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..7cdb485
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,115 @@
+============
+Open vSwitch
+============
+
+Build Status
+------------
+
+.. image:: https://travis-ci.org/openvswitch/ovs.png
+    :target: https://travis-ci.org/openvswitch/ovs
+
+What is Open vSwitch?
+---------------------
+
+Open vSwitch is a multilayer software switch licensed under the open source
+Apache 2 license.  Our goal is to implement a production quality switch
+platform that supports standard management interfaces and opens the forwarding
+functions to programmatic extension and control.
+
+Open vSwitch is well suited to function as a virtual switch in VM environments.
+In addition to exposing standard control and visibility interfaces to the
+virtual networking layer, it was designed to support distribution across
+multiple physical servers.  Open vSwitch supports multiple Linux-based
+virtualization technologies including Xen/XenServer, KVM, and VirtualBox.
+
+The bulk of the code is written in platform-independent C and is easily ported
+to other environments.  The current release of Open vSwitch supports the
+following features:
+
+- Standard 802.1Q VLAN model with trunk and access ports
+- NIC bonding with or without LACP on upstream switch
+- NetFlow, sFlow(R), and mirroring for increased visibility
+- QoS (Quality of Service) configuration, plus policing
+- Geneve, GRE, VXLAN, STT, and LISP tunneling
+- 802.1ag connectivity fault management
+- OpenFlow 1.0 plus numerous extensions
+- Transactional configuration database with C and Python bindings
+- High-performance forwarding using a Linux kernel module
+
+The included Linux kernel module supports Linux 3.10 and up.
+
+Open vSwitch can also operate, at a cost in performance, entirely in userspace,
+without assistance from a kernel module.  This userspace implementation should
+be easier to port than the kernel-based switch.  It is considered experimental.
+
+What's here?
+------------
+
+The main components of this distribution are:
+
+- ovs-vswitchd, a daemon that implements the switch, along with a companion
+  Linux kernel module for flow-based switching.
+- ovsdb-server, a lightweight database server that ovs-vswitchd queries to
+  obtain its configuration.
+- ovs-dpctl, a tool for configuring the switch kernel module.
+- Scripts and specs for building RPMs for Citrix XenServer and Red Hat
+  Enterprise Linux.  The XenServer RPMs allow Open vSwitch to be installed on a
+  Citrix XenServer host as a drop-in replacement for its switch, with
+  additional functionality.
+- ovs-vsctl, a utility for querying and updating the configuration of
+  ovs-vswitchd.
+- ovs-appctl, a utility that sends commands to running Open vSwitch daemons.
+
+Open vSwitch also provides some tools:
+
+- ovs-ofctl, a utility for querying and controlling OpenFlow switches and
+  controllers.
+- ovs-pki, a utility for creating and managing the public-key infrastructure
+  for OpenFlow switches.
+- ovs-testcontroller, a simple OpenFlow controller that may be useful for
+  testing (though not for production).
+- A patch to tcpdump that enables it to parse OpenFlow messages.
+
+What other documentation is available?
+--------------------------------------
+
+To install Open vSwitch on a regular Linux or FreeBSD host, please read the
+`installation guide <INSTALL.md>`__. For specifics around installation on a
+specific platform, please see one of the below installation guides:
+
+- `Debian <INSTALL.Debian.md>`__
+- `Fedora <INSTALL.Fedora.md>`__
+- `RHEL <INSTALL.RHEL.md>`__
+- `XenServer <INSTALL.XenServer.md>`__
+
+To use Open vSwitch...
+
+- ...with Docker on Linux, see `here <INSTALL.Docker.md>`__.
+
+- ...with KVM on Linux, see `here <INSTALL.md>`__ and `here
+  <INSTALL.KVM.md>`__.
+
+- ...with Libvirt, see `here <INSTALL.Libvirt.md>`__.
+
+- ...without using a kernel module, see `here <INSTALL.userspace.md>`__.
+
+- ...with DPDK, see `here <INSTALL.DPDK.md>`__.
+
+- ...with SELinux, see `here <INSTALL.SELinux.md>`__.
+
+For answers to common questions, refer to the `FAQ <FAQ.md>`__.
+
+To learn how to set up SSL support for Open vSwitch, see `here
+<INSTALL.SSL.md>`__.
+
+To learn about some advanced features of the Open vSwitch software switch, read
+the `tutorial <tutorial/Tutorial.md>`__.
+
+Each Open vSwitch userspace program is accompanied by a manpage.  Many of the
+manpages are customized to your configuration as part of the build process, so
+we recommend building Open vSwitch before reading the manpages.
+
+Contact
+-------
+
+bugs at openvswitch.org
diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in
index eda8767..42463b4 100644
--- a/rhel/openvswitch-fedora.spec.in
+++ b/rhel/openvswitch-fedora.spec.in
@@ -478,7 +478,7 @@ fi
 %{_mandir}/man8/ovs-vswitchd.8*
 %{_mandir}/man8/ovs-parse-backtrace.8*
 %{_mandir}/man8/ovs-testcontroller.8*
-%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.md WHY-OVS.md
+%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.md
 %doc FAQ.md NEWS INSTALL.DPDK.md rhel/README.RHEL
 /var/lib/openvswitch
 /var/log/openvswitch
diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in
index 0ef0b04..34b279b 100644
--- a/rhel/openvswitch.spec.in
+++ b/rhel/openvswitch.spec.in
@@ -247,7 +247,7 @@ exit 0
 /usr/share/openvswitch/scripts/sysconfig.template
 /usr/share/openvswitch/vswitch.ovsschema
 /usr/share/openvswitch/vtep.ovsschema
-%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.md WHY-OVS.md FAQ.md NEWS
+%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.md FAQ.md NEWS
 %doc INSTALL.DPDK.md rhel/README.RHEL README-native-tunneling.md
 /var/lib/openvswitch
 /var/log/openvswitch
diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8
index 6b8fba7..ca14e53 100644
--- a/utilities/ovs-ctl.8
+++ b/utilities/ovs-ctl.8
@@ -502,5 +502,5 @@ distribution are good examples of how to use \fBovs\-ctl\fR.
 .
 .SH "SEE ALSO"
 .
-\fBREADME.md\fR, \fBINSTALL.Linux.md\fR, \fBovsdb\-server\fR(8),
+\fBREADME.rst\fR, \fBINSTALL.Linux.md\fR, \fBovsdb\-server\fR(8),
 \fBovs\-vswitchd\fR(8).
-- 
2.7.4




More information about the dev mailing list