[ovs-dev] [PATCH v2 05/11] doc: Populate 'install', 'howto' sections

Stephen Finucane stephen at that.guru
Thu Dec 8 12:55:24 UTC 2016


This is a dumb move of all 'INSTALL*' docs, with very little
refactoring (mostly updating links and making the titles a little more
consistent. Additional refactoring will be done in subsequent changes.

Signed-off-by: Stephen Finucane <stephen at that.guru>
---
 Documentation/automake.mk                          | 16 +++++++
 .../howto/docker.rst                               | 13 +++---
 Documentation/howto/index.rst                      |  6 +++
 INSTALL.KVM.rst => Documentation/howto/kvm.rst     | 15 +++---
 .../howto/libvirt.rst                              | 11 ++---
 .../howto/selinux.rst                              |  8 ++--
 INSTALL.SSL.rst => Documentation/howto/ssl.rst     |  4 +-
 Documentation/index.rst                            | 12 ++++-
 .../internals/contributing/documentation-style.rst |  4 +-
 .../intro/install/bash-completion.rst              |  0
 .../intro/install/debian.rst                       | 16 +++----
 .../intro/install/dpdk-advanced.rst                | 23 +++++----
 .../intro/install/dpdk.rst                         | 54 ++++++++++------------
 .../intro/install/fedora.rst                       | 17 +++----
 .../intro/install/general.rst                      | 27 ++++-------
 Documentation/intro/install/index.rst              | 33 +++++++++++++
 .../intro/install/netbsd.rst                       |  7 ++-
 .../intro/install/rhel.rst                         | 38 +++++++++------
 .../intro/install/userspace.rst                    | 14 +++---
 .../intro/install/windows.rst                      |  3 +-
 .../intro/install/xenserver.rst                    | 12 ++---
 FAQ.rst                                            | 23 +++++----
 Makefile.am                                        | 15 ------
 PORTING.rst                                        |  8 ++--
 README.rst                                         | 32 +++----------
 debian/openvswitch-common.docs                     |  2 -
 rhel/openvswitch-fedora.spec.in                    |  4 +-
 rhel/openvswitch.spec.in                           |  4 +-
 tutorial/ovn-tutorial.rst                          |  5 +-
 tutorial/tutorial.rst                              |  8 ++--
 utilities/automake.mk                              |  2 -
 utilities/ovs-ctl.8                                |  3 +-
 utilities/ovs-vsctl.8.in                           |  6 +--
 vswitchd/ovs-vswitchd.8.in                         | 10 ++--
 vtep/README.ovs-vtep.rst                           | 15 +++---
 vtep/vtep-ctl.8.in                                 |  6 +--
 36 files changed, 246 insertions(+), 230 deletions(-)
 rename INSTALL.Docker.rst => Documentation/howto/docker.rst (96%)
 rename INSTALL.KVM.rst => Documentation/howto/kvm.rst (86%)
 rename INSTALL.Libvirt.rst => Documentation/howto/libvirt.rst (87%)
 rename INSTALL.SELinux.rst => Documentation/howto/selinux.rst (97%)
 rename INSTALL.SSL.rst => Documentation/howto/ssl.rst (98%)
 rename utilities/ovs-command-bashcomp.INSTALL.rst => Documentation/intro/install/bash-completion.rst (100%)
 rename INSTALL.Debian.rst => Documentation/intro/install/debian.rst (94%)
 rename INSTALL.DPDK-ADVANCED.rst => Documentation/intro/install/dpdk-advanced.rst (98%)
 rename INSTALL.DPDK.rst => Documentation/intro/install/dpdk.rst (92%)
 rename INSTALL.Fedora.rst => Documentation/intro/install/fedora.rst (90%)
 rename INSTALL.rst => Documentation/intro/install/general.rst (97%)
 rename INSTALL.NetBSD.rst => Documentation/intro/install/netbsd.rst (89%)
 rename INSTALL.RHEL.rst => Documentation/intro/install/rhel.rst (87%)
 rename INSTALL.userspace.rst => Documentation/intro/install/userspace.rst (92%)
 rename INSTALL.Windows.rst => Documentation/intro/install/windows.rst (99%)
 rename INSTALL.XenServer.rst => Documentation/intro/install/xenserver.rst (96%)

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 5d528ae..50e9808 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -9,9 +9,25 @@ EXTRA_DIST += \
 	Documentation/contents.rst \
 	Documentation/intro/index.rst \
 	Documentation/intro/install/index.rst \
+	Documentation/intro/install/bash-completion.rst \
+	Documentation/intro/install/debian.rst \
+	Documentation/intro/install/dpdk-advanced.rst \
+	Documentation/intro/install/dpdk.rst \
+	Documentation/intro/install/fedora.rst \
+	Documentation/intro/install/general.rst \
+	Documentation/intro/install/netbsd.rst \
+	Documentation/intro/install/rhel.rst \
+	Documentation/intro/install/userspace.rst \
+	Documentation/intro/install/windows.rst \
+	Documentation/intro/install/xenserver.rst \
 	Documentation/tutorials/index.rst \
 	Documentation/topics/index.rst \
 	Documentation/howto/index.rst \
+	Documentation/howto/docker.rst \
+	Documentation/howto/kvm.rst \
+	Documentation/howto/libvirt.rst \
+	Documentation/howto/selinux.rst \
+	Documentation/howto/ssl.rst \
 	Documentation/ref/index.rst \
 	Documentation/faq/index.rst \
 	Documentation/internals/index.rst
diff --git a/INSTALL.Docker.rst b/Documentation/howto/docker.rst
similarity index 96%
rename from INSTALL.Docker.rst
rename to Documentation/howto/docker.rst
index 4d66172..e23ca75 100644
--- a/INSTALL.Docker.rst
+++ b/Documentation/howto/docker.rst
@@ -37,8 +37,7 @@ or later.
 .. note::
 
   You must build and install Open vSwitch before proceeding with the below
-  guide. Refer to the `installation guide <INSTALL.rst>`__ for more
-  information.
+  guide. Refer to :doc:`/intro/install/index` for more information.
 
 Setup
 -----
@@ -162,10 +161,10 @@ The "overlay" mode
      Open vSwitch Python modules are installed. If you installed Open vSwitch
      Python modules via the Debian package of ``python-openvswitch`` or via pip
      by running ``pip install ovs``, you do not need to specify the PATH. If
-     you installed it by following the instructions in the `installation guide
-     <INSTALL.rst>`__, then you should specify the PATH. In this case, the PATH
-     depends on the options passed to ``./configure``. It is usually either
-     ``/usr/share/openvswitch/python`` or
+     you installed it by following the instructions in
+     :doc:`/intro/install/general`, then you should specify the PATH. In this
+     case, the PATH depends on the options passed to ``./configure``. It is
+     usually either ``/usr/share/openvswitch/python`` or
      ``/usr/local/share/openvswitch/python``
 
 Docker has inbuilt primitives that closely match OVN's logical switches and
@@ -290,7 +289,7 @@ The "underlay" mode
    Depending on your VM, you can make the above step persistent across reboots.
    For example, if your VM is Debian/Ubuntu-based, read
    `openvswitch-switch.README.Debian` found in `debian` folder. If your VM is
-   RHEL-based, refer to the `RHEL install guide <../../INSTALL.RHEL.rst>`__.
+   RHEL-based, refer to :doc:`/intro/install/rhel`.
 
 3. Start the Open vSwitch network driver
 
diff --git a/Documentation/howto/index.rst b/Documentation/howto/index.rst
index 1c4d9d2..81b2931 100644
--- a/Documentation/howto/index.rst
+++ b/Documentation/howto/index.rst
@@ -32,3 +32,9 @@ topics covered herein, refer to :doc:`/topics/index`.
 
 .. toctree::
    :maxdepth: 2
+
+   kvm
+   selinux
+   libvirt
+   ssl
+   docker
diff --git a/INSTALL.KVM.rst b/Documentation/howto/kvm.rst
similarity index 86%
rename from INSTALL.KVM.rst
rename to Documentation/howto/kvm.rst
index 4a5b372..4b43af3 100644
--- a/INSTALL.KVM.rst
+++ b/Documentation/howto/kvm.rst
@@ -21,17 +21,16 @@
 
       Avoid deeper levels because they do not render well.
 
-================================
-How to Use Open vSwitch with KVM
-================================
+=====================
+Open vSwitch with KVM
+=====================
 
 This document describes how to use Open vSwitch with the Kernel-based Virtual
 Machine (KVM).
 
 .. note::
 
-  This document assumes that you have read and followed the `installation guide
-  <INSTALL.rst>`__ to get Open vSwitch setup on your Linux system.
+  This document assumes that you have Open vSwitch set up on a Linux system.
 
 Setup
 -----
@@ -64,9 +63,9 @@ Create the following two files and store them in known locations. For example::
     /sbin/ifconfig $1 0.0.0.0 down
     ovs-vsctl del-port ${switch} $1
 
-The basic usage of Open vSwitch is described at the end of the `installation
-guide <INSTALL.rst>`__. If you haven't already, create a bridge named ``br0``
-with the following command::
+The basic usage of Open vSwitch is described at the end of
+:doc:`/intro/install/general`. If you haven't already, create a bridge named
+``br0`` with the following command::
 
     $ ovs-vsctl add-br br0
 
diff --git a/INSTALL.Libvirt.rst b/Documentation/howto/libvirt.rst
similarity index 87%
rename from INSTALL.Libvirt.rst
rename to Documentation/howto/libvirt.rst
index b32944c..0b303d5 100644
--- a/INSTALL.Libvirt.rst
+++ b/Documentation/howto/libvirt.rst
@@ -26,12 +26,11 @@ Open vSwitch with Libvirt
 =========================
 
 This document describes how to use Open vSwitch with Libvirt 0.9.11 or later.
-This document assumes that you followed the `general installation guide
-<INSTALL.rst>`__ or installed Open vSwitch from distribution packaging such as
-a .deb or .rpm.  The Open vSwitch support is included by default in Libvirt
-0.9.11. Consult www.libvirt.org for instructions on how to build the latest
-Libvirt, if your Linux distribution by default comes with an older Libvirt
-release.
+This document assumes that you followed :doc:`/intro/install/general` or
+installed Open vSwitch from distribution packaging such as a .deb or .rpm.  The
+Open vSwitch support is included by default in Libvirt 0.9.11. Consult
+www.libvirt.org for instructions on how to build the latest Libvirt, if your
+Linux distribution by default comes with an older Libvirt release.
 
 Limitations
 -----------
diff --git a/INSTALL.SELinux.rst b/Documentation/howto/selinux.rst
similarity index 97%
rename from INSTALL.SELinux.rst
rename to Documentation/howto/selinux.rst
index 8593d7f..ad556da 100644
--- a/INSTALL.SELinux.rst
+++ b/Documentation/howto/selinux.rst
@@ -74,8 +74,8 @@ anticipated the feature set that your SELinux implementation supports.
 Installation
 ------------
 
-Refer to the `Fedora installation guide <INSTALL.Fedora.rst>`__ for
-instructions on how to build all Open vSwitch rpm packages.
+Refer to :doc:`/intro/install/fedora` for instructions on how to build all Open
+vSwitch rpm packages.
 
 Once the package is built, install it on your Linux distribution::
 
@@ -159,8 +159,8 @@ vSwitch developer mailing list:
    Implications of this are that you should use only those SELinux policy
    features that are supported by the lowest SELinux version out there.
    Typically this means that you should test your SELinux policy changes on the
-   oldest RHEL or CentOS version that this OVS version supports.  Check
-   INSTALL.Fedora.rst file to find out this.
+   oldest RHEL or CentOS version that this OVS version supports. Refer to
+   :doc:`/intro/install/fedora` to find out this.
 
 3. The SELinux policy is enforced only when state transition to
    ``openvswitch_t`` domain happens.
diff --git a/INSTALL.SSL.rst b/Documentation/howto/ssl.rst
similarity index 98%
rename from INSTALL.SSL.rst
rename to Documentation/howto/ssl.rst
index 8edd25e..3085206 100644
--- a/INSTALL.SSL.rst
+++ b/Documentation/howto/ssl.rst
@@ -31,8 +31,8 @@ OpenSSL. SSL support ensures integrity and confidentiality of the OpenFlow
 connections, increasing network security.
 
 This document describes how to configure an Open vSwitch to connect to an
-OpenFlow controller over SSL.  Refer to the `general installation guide
-<INSTALL.rst>`__ for instructions on building Open vSwitch with SSL support.
+OpenFlow controller over SSL.  Refer to :doc:`/intro/install/general`. for
+instructions on building Open vSwitch with SSL support.
 
 Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by RFC 2246,
 which is very similar to SSL version 3.0.  TLSv1 was released in January 1999,
diff --git a/Documentation/index.rst b/Documentation/index.rst
index a46407a..be794f1 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -45,7 +45,17 @@ The Open vSwitch documentation is organised into multiple sections:
 First Steps
 -----------
 
-**TODO**
+Getting started with Open vSwitch (OVS) or Open Virtual Network (OVN) for Open
+vSwitch? Start here.
+
+- **Install:** :doc:`intro/install/general` |
+  :doc:`intro/install/userspace` |
+  :doc:`intro/install/netbsd` |
+  :doc:`intro/install/windows` |
+  :doc:`intro/install/xenserver` |
+  :doc:`intro/install/dpdk`
+
+- **Tutorials:** **TODO**
 
 Deeper Dive
 -----------
diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst
index 756f167..c32921e 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -29,8 +29,8 @@ Open vSwitch Documentation Style
 
 This file describes the documentation style used in all documentation found in
 Open vSwitch. Documentation includes any documents found in ``Documentation``
-along with any ``README``, ``INSTALL``, or generally ``rst`` suffixed documents
-found in the project tree.
+along with any ``README``, ``MAINTAINERS``, or generally ``rst`` suffixed
+documents found in the project tree.
 
 reStructuredText vs. Sphinx
 ---------------------------
diff --git a/utilities/ovs-command-bashcomp.INSTALL.rst b/Documentation/intro/install/bash-completion.rst
similarity index 100%
rename from utilities/ovs-command-bashcomp.INSTALL.rst
rename to Documentation/intro/install/bash-completion.rst
diff --git a/INSTALL.Debian.rst b/Documentation/intro/install/debian.rst
similarity index 94%
rename from INSTALL.Debian.rst
rename to Documentation/intro/install/debian.rst
index 6086b82..6484331 100644
--- a/INSTALL.Debian.rst
+++ b/Documentation/intro/install/debian.rst
@@ -21,13 +21,13 @@
 
       Avoid deeper levels because they do not render well.
 
-=========================================
-Building Debian Packages for Open vSwitch
-=========================================
+=================================
+Debian Packaging 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.
+install Open vSwitch on Debian without building Debian packages, refer to
+:doc:`general` instead.
 
 .. note::
   These instructions should also work on Ubuntu and other Debian derivative
@@ -117,7 +117,7 @@ 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.
 
-Bug Reporting
--------------
+Reporting Bugs
+--------------
 
-Please report problems to bugs at openvswitch.org.
+Report problems to bugs at openvswitch.org.
diff --git a/INSTALL.DPDK-ADVANCED.rst b/Documentation/intro/install/dpdk-advanced.rst
similarity index 98%
rename from INSTALL.DPDK-ADVANCED.rst
rename to Documentation/intro/install/dpdk-advanced.rst
index 1c2437d..44d1cd7 100644
--- a/INSTALL.DPDK-ADVANCED.rst
+++ b/Documentation/intro/install/dpdk-advanced.rst
@@ -40,8 +40,8 @@ Open vSwitch against the shared DPDK library.
   Minor performance loss is seen with OVS when using shared DPDK library as
   compared to static library.
 
-To build Open vSwitch using DPDK as a shared library, first refer to the `DPDK
-installation guide`_ for download instructions for DPDK and OVS.
+To build Open vSwitch using DPDK as a shared library, first refer to
+:doc:`/intro/install/dpdk` for download instructions for DPDK and OVS.
 
 Once DPDK and OVS have been downloaded, you must configure the DPDK library
 accordingly. Simply set ``CONFIG_RTE_BUILD_SHARED_LIB=y`` in
@@ -53,7 +53,7 @@ built as usual. For example::
     $ make install T=$DPDK_TARGET DESTDIR=install
 
 Once DPDK is built, export the DPDK shared library location and setup OVS as
-detailed in the `DPDK installation guide`_::
+detailed in :doc:`/intro/install/dpdk`::
 
     $ export LD_LIBRARY_PATH=$DPDK_DIR/x86_64-native-linuxapp-gcc/lib
 
@@ -345,8 +345,8 @@ OVS Testcases
 PHY-VM-PHY (vHost Loopback)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The `DPDK installation guide`_ details steps for PHY-VM-PHY loopback testcase
-and packet forwarding using DPDK testpmd application in the Guest VM. For users
+:doc:`/intro/install/dpdk` details steps for PHY-VM-PHY loopback testcase and
+packet forwarding using DPDK testpmd application in the Guest VM. For users
 wishing to do packet forwarding using kernel stack below, you need to run the
 below commands on the guest::
 
@@ -367,7 +367,7 @@ PHY-VM-PHY (IVSHMEM)
 ~~~~~~~~~~~~~~~~~~~~
 
 IVSHMEM can also be validated using the PHY-VM-PHY configuration. To begin,
-follow the steps described in the `DPDK installation guide`_ to create and
+follow the steps described in the :doc:`/intro/install/dpdk` to create and
 initialize the database, start ovs-vswitchd and add ``dpdk``-type devices to
 bridge ``br0``. Once complete, follow the below steps:
 
@@ -427,9 +427,10 @@ PHY-VM-PHY (vHost Multiqueue)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 vHost Multique functionality can also be validated using the PHY-VM-PHY
-configuration. To begin, follow the steps described in the `DPDK installation
-guide`_ to create and initialize the database, start ovs-vswitchd and add
-``dpdk``-type devices to bridge ``br0``. Once complete, follow the below steps:
+configuration. To begin, follow the steps described in
+:doc:`/intro/install/dpdk` to create and initialize the database, start
+ovs-vswitchd and add ``dpdk``-type devices to bridge ``br0``. Once complete,
+follow the below steps:
 
 1. Configure PMD and RXQs.
 
@@ -672,7 +673,7 @@ itself.
 
 2. Instantiate the VM
 
-   - Copy the XML configuration described in the `DPDK installation guide`_.
+   - Copy the XML configuration described in :doc:`/intro/install/dpdk`
 
    - Start the VM::
 
@@ -935,5 +936,3 @@ Bug Reporting
 -------------
 
 Report problems to bugs at openvswitch.org.
-
-.. _DPDK installation guide: INSTALL.DPDK.rst
diff --git a/INSTALL.DPDK.rst b/Documentation/intro/install/dpdk.rst
similarity index 92%
rename from INSTALL.DPDK.rst
rename to Documentation/intro/install/dpdk.rst
index 10ccfdf..7724c8a 100644
--- a/INSTALL.DPDK.rst
+++ b/Documentation/intro/install/dpdk.rst
@@ -35,8 +35,8 @@ userspace.
 Build requirements
 ------------------
 
-In addition to the requirements described in the `installation guide
-<INSTALL.rst>`__, building Open vSwitch with DPDK will require the following:
+In addition to the requirements described in :doc:`general`, building Open
+vSwitch with DPDK will require the following:
 
 - DPDK 16.11
 
@@ -53,9 +53,10 @@ In addition to the requirements described in the `installation guide
   present, it will be necessary to upgrade your kernel or build a custom kernel
   with these flags enabled.
 
+.. TODO(stephenfin): drag the below information in from dpdk-advanced
+
 Detailed system requirements can be found at `DPDK requirements`_, while more
-detailed install information can be found in the `advanced installation guide
-<INSTALL.DPDK-ADVANCED.rst>`__.
+detailed install information can be found in :doc:`dpdk-advanced`.
 
 .. _DPDK supported NIC: http://dpdk.org/doc/nics
 .. _DPDK requirements: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html
@@ -100,28 +101,25 @@ has to be configured with DPDK support (``--with-dpdk``).
 
 .. _OVS sources: http://openvswitch.org/releases/
 
-1. Ensure the standard OVS requirements, described in the `installation guide
-   <INSTALL.rst>`__, are installed.
+1. Ensure the standard OVS requirements, described in
+   :ref:`general-build-reqs`, are installed
 
-2. Bootstrap, if required, as described in the `installation guide
-   <INSTALL.rst>`__.
+2. Bootstrap, if required, as described in :ref:`general-bootstrapping`
 
 3. Configure the package using the ``--with-dpdk`` flag::
 
        $ ./configure --with-dpdk=$DPDK_BUILD
 
    where ``DPDK_BUILD`` is the path to the built DPDK library. This can be
-   skipped if DPDK library is installed in its default location.
+   skipped if DPDK library is installed in its default location
 
    .. note::
      While ``--with-dpdk`` is required, you can pass any other configuration
-     option described in the `installation guide <INSTALL.rst>`__.
+     option described in :ref:`general-configuring`.
 
-4. Build and install OVS, as described in the `installation guide
-   <INSTALL.rst>`__.
+4. Build and install OVS, as described in :ref:`general-building`
 
-Additional information can be found in the `installation guide
-<INSTALL.rst>`__.
+Additional information can be found in :doc:`general`.
 
 Setup
 -----
@@ -182,12 +180,11 @@ to the VFIO driver::
 Setup OVS
 ~~~~~~~~~
 
-Open vSwitch should be started as described in the `installation guide
-<INSTALL.rst>`__ with the exception of ovs-vswitchd, which requires some
-special configuration to enable DPDK functionality. DPDK configuration
-arguments can be passed to ovs-vswitchd via the ``other_config`` column of the
-``Open_vSwitch`` table. At a minimum, the ``dpdk-init`` option must be set to
-``true``. For example::
+Open vSwitch should be started as described in :doc:`general` with the
+exception of ovs-vswitchd, which requires some special configuration to enable
+DPDK functionality. DPDK configuration arguments can be passed to ovs-vswitchd
+via the ``other_config`` column of the ``Open_vSwitch`` table. At a minimum,
+the ``dpdk-init`` option must be set to ``true``. For example::
 
     $ export DB_SOCK=/usr/local/var/run/openvswitch/db.sock
     $ ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true
@@ -228,8 +225,7 @@ threads and pin them to cores 1,2, run::
 
     $ ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=0x6
 
-For details on using ivshmem with DPDK, refer to `the advanced installation
-guide <INSTALL.DPDK-ADVANCED.rst>`__.
+For details on using ivshmem with DPDK, refer to :doc:`dpdk-advanced`.
 
 Refer to ovs-vswitchd.conf.db(5) for additional information on configuration
 options.
@@ -338,7 +334,7 @@ DPDK 'testpmd' application can be run in the Guest VM for high speed packet
 forwarding between vhostuser ports. DPDK and testpmd application has to be
 compiled on the guest VM. Below are the steps for setting up the testpmd
 application in the VM. More information on the vhostuser ports can be found in
-the `advanced install guide <INSTALL.DPDK-ADVANCED.rst>`__.
+:doc:`dpdk-advanced`.
 
 .. note::
   Support for DPDK in the guest requires QEMU >= 2.2.0.
@@ -573,13 +569,13 @@ When you finish testing, bind the vNICs back to kernel::
       $ $DPDK_DIR/tools/dpdk-devbind.py --status
 
 .. note::
-  More information on the dpdkvhostuser ports can be found in the `advanced
-  installation guide <INSTALL.DPDK-ADVANCED.rst>`__.
+  More information on the dpdkvhostuser ports can be found in
+  :doc:`dpdk-advanced`.
 
 PHY-VM-PHY (IVSHMEM loopback)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Refer to the `advanced installation guide <INSTALL.DPDK-ADVANCED.rst>`__.
+Refer to the :doc:`dpdk-advanced`.
 
 Limitations
 ------------
@@ -598,7 +594,7 @@ Limitations
 
 .. _DPDK release notes: http://dpdk.org/doc/guides/rel_notes/release_16_11.html
 
-Bug Reporting
--------------
+Reporting Bugs
+--------------
 
-Please report problems to bugs at openvswitch.org.
+Report problems to bugs at openvswitch.org.
diff --git a/INSTALL.Fedora.rst b/Documentation/intro/install/fedora.rst
similarity index 90%
rename from INSTALL.Fedora.rst
rename to Documentation/intro/install/fedora.rst
index b9be0ed..7363538 100644
--- a/INSTALL.Fedora.rst
+++ b/Documentation/intro/install/fedora.rst
@@ -21,14 +21,14 @@
 
       Avoid deeper levels because they do not render well.
 
-============================
-Open vSwitch on Fedora Linux
-============================
+===========================================
+Fedora, RHEL 7.x Packaging for Open vSwitch
+===========================================
 
 This document provides instructions for building and installing Open vSwitch
 RPM packages on a Fedora Linux host. Instructions for the installation of Open
 vSwitch on a Fedora Linux host without using RPM packages can be found in the
-`general installation guide <INSTALL.rst>`__.
+:doc:`general`.
 
 These instructions have been tested with Fedora 23, and are also applicable for
 RHEL 7.x and its derivatives, including CentOS 7.x and Scientific Linux 7.x.
@@ -37,8 +37,7 @@ Build Requirements
 ------------------
 
 To build packages for a Fedora Linux host, you will need the packages described
-in the `general installation guide <INSTALL.rst>`__. Specific packages (by
-package name) include:
+in the :doc:`general`. Specific packages (by package name) include:
 
 - rpm-build
 - autoconf automake libtool
@@ -56,14 +55,12 @@ And (optionally):
 Bootstraping
 ------------
 
-Refer to the *Bootstrapping* section of the `general installation guide
-<INSTALL.rst>`__.
+Refer to :ref:`general-bootstrapping`.
 
 Configuring
 -----------
 
-Refer to the *Configuring* section of the `general installation guide
-<INSTALL.rst>`__.
+Refer to :ref:`general-configuring`.
 
 Building
 --------
diff --git a/INSTALL.rst b/Documentation/intro/install/general.rst
similarity index 97%
rename from INSTALL.rst
rename to Documentation/intro/install/general.rst
index d934c1f..631dc9b 100644
--- a/INSTALL.rst
+++ b/Documentation/intro/install/general.rst
@@ -27,15 +27,7 @@ Open vSwitch on Linux, FreeBSD and NetBSD
 
 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.rst>`__
-- `Fedora <INSTALL.Fedora.rst>`__
-- `RHEL <INSTALL.RHEL.rst>`__
-- `XenServer <INSTALL.XenServer.rst>`__
-- `NetBSD <INSTALL.NetBSD.rst>`__
-- `Windows <INSTALL.Windows.rst>`__
-- `DPDK <INSTALL.DPDK.rst>`__
+platform, refer to one of the other installation guides listed in :doc:`index`.
 
 .. _general-build-reqs:
 
@@ -55,8 +47,8 @@ need the following software:
     thread-safety checks. For Ubuntu, there are nightly built packages
     available on clang's website.
 
-  - MSVC 2013. See the `Windows installation guide <INSTALL.Windows>`__
-    for additional Windows build instructions.
+  - MSVC 2013. Refer to :doc:`windows` for additional Windows build
+    instructions.
 
   While OVS may be compatible with other compilers, optimal support for atomic
   operations may be missing, making OVS very slow (see ``lib/ovs-atomic.h``).
@@ -79,14 +71,13 @@ vSwitch distribution or to use the kernel module built into the Linux kernel
 (version 3.3 or later). See the `FAQ <FAQ.rst>`__ question "What features
 are not available in the Open vSwitch kernel datapath that ships as part of the
 upstream Linux kernel?" for more information on this trade-off. You may also
-use the userspace-only implementation, at some cost in features and performance
-(see the `userspace installation guide <INSTALL.userspace.rst>`__ for details).
+use the userspace-only implementation, at some cost in features and
+performance. Refer to :doc:`userspace` for details.
 
 To compile the kernel module on Linux, you must also install the
 following:
 
-- A supported Linux kernel version. Refer to the `README <README.rst>`__
-  for a list of supported versions.
+- A supported Linux kernel version.
 
   For optional support of ingress policing, you must enable kernel
   configuration options ``NET_CLS_BASIC``, ``NET_SCH_INGRESS``, and
@@ -865,7 +856,7 @@ You should invoke scan-view to view analysis results. The last line of output
 from ``clang-analyze`` will list the command (containing results directory)
 that you should invoke to view the results on a browser.
 
-Bug Reporting
--------------
+Reporting Bugs
+--------------
 
-Please report problems to bugs at openvswitch.org.
+Report problems to bugs at openvswitch.org.
diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst
index 35dc67c..2366388 100644
--- a/Documentation/intro/install/index.rst
+++ b/Documentation/intro/install/index.rst
@@ -30,5 +30,38 @@ Installing Open vSwitch
 A collection of guides detailing how to install Open vSwitch in a variety of
 different environments and using different configurations.
 
+Installation from Source
+------------------------
+
+.. TODO(stephenfin): The DPDK-ADVANCED doc is mostly usage material. The
+   install related instructions should be moved to the main doc, while the
+   rest should be moved to howto and topic docs
+
+.. TODO(stephenfin): Based on the title alone, the NetBSD doc should probably
+   be merged into the general install doc
+
+.. toctree::
+   :maxdepth: 2
+
+   general
+   netbsd
+   windows
+   xenserver
+   userspace
+   dpdk
+   dpdk-advanced
+   bash-completion
+
+Installation from Packages
+--------------------------
+
+Open vSwitch is packaged on a variety of distributions. The tooling required to
+build these packages is included in the Open vSwitch tree. The instructions are
+provided below.
+
 .. toctree::
    :maxdepth: 2
+
+   debian
+   fedora
+   rhel
diff --git a/INSTALL.NetBSD.rst b/Documentation/intro/install/netbsd.rst
similarity index 89%
rename from INSTALL.NetBSD.rst
rename to Documentation/intro/install/netbsd.rst
index e204c57..2b52eaf 100644
--- a/INSTALL.NetBSD.rst
+++ b/Documentation/intro/install/netbsd.rst
@@ -36,8 +36,8 @@ you need at least the following packages.
 - py27-xml
 - pkg_alternatives
 
-Some components have additional requirements. Refer to the `general
-installation guide <INSTALL.rst>`__.
+Some components have additional requirements. Refer to :doc:`general` for more
+information.
 
 Assuming you are running NetBSD/amd64 6.1.2, you can download and install
 pre-built binary packages as the following::
@@ -58,5 +58,4 @@ As all executables installed with pkgsrc are placed in ``/usr/pkg/bin/``
 directory, it might be a good idea to add it to your PATH.
 
 Open vSwitch on NetBSD is currently "userspace switch" implementation in the
-sense described in the `userspace installation guide <INSTALL.userspace.rst>`__
-and `porting guide <PORTING.rst>`__.
+sense described in :doc:`userspace` and the `porting guide`.
diff --git a/INSTALL.RHEL.rst b/Documentation/intro/install/rhel.rst
similarity index 87%
rename from INSTALL.RHEL.rst
rename to Documentation/intro/install/rhel.rst
index 125c55d..498fd8f 100644
--- a/INSTALL.RHEL.rst
+++ b/Documentation/intro/install/rhel.rst
@@ -22,18 +22,20 @@
       Avoid deeper levels because they do not render well.
 
 ========================================
-Open vSwitch on Red Hat Enterprise Linux
+RHEL 5.6, 6.x Packaging for Open vSwitch
 ========================================
 
 This document describes how to build and install Open vSwitch on a Red Hat
 Enterprise Linux (RHEL) host.  If you want to install Open vSwitch on a generic
-Linux host, see the `general installation guide <INSTALL.rst>`__ instead.
+Linux host, refer to :doc:`general` instead.
 
 We have tested these instructions with RHEL 5.6 and RHEL 6.0.
 
 For RHEL 7.x (or derivatives, such as CentOS 7.x), you should follow the
-instructions in the `Fedora installation guide <INSTALL.Fedora.rst>`__.  The
-Fedora spec files are used for RHEL 7.x.
+instructions in the :doc:`fedora`.  The Fedora spec files are used for RHEL
+7.x.
+
+.. _rhel-prerequisites:
 
 Prerequisites
 -------------
@@ -69,21 +71,23 @@ Build Requirements
 ------------------
 
 To compile the RPMs, you will need to install the packages described in the
-`general installation guide <INSTALL.rst>`__ along with some additional
-packages. These can be installed with the below command::
+:doc:`general` along with some additional packages. These can be installed with
+the below command::
 
     $ yum install gcc make python-devel openssl-devel kernel-devel graphviz \
         kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \
         libtool
 
+.. _rhel-bootstrapping:
+
 Bootstrapping and Configuring
 -----------------------------
 
-If you are building from a distribution tarball, skip to *Building*. If not,
-you must be building from an Open vSwitch Git tree.  Determine what version of
-Autoconf is installed (e.g. run ``autoconf --version``).  If it is not at least
-version 2.63, then you must upgrade or use another machine to build the
-packages.
+If you are building from a distribution tarball, skip to :ref:`rhel-building`.
+If not, you must be building from an Open vSwitch Git tree.  Determine what
+version of Autoconf is installed (e.g. run ``autoconf --version``).  If it is
+not at least version 2.63, then you must upgrade or use another machine to
+build the packages.
 
 Assuming all requirements have been met, build the tarball by running::
 
@@ -91,10 +95,10 @@ Assuming all requirements have been met, build the tarball by running::
     $ ./configure
     $ make dist
 
-You must run this on a machine that has the tools listed in the `general
-installation guide <INSTALL.rst>`__ as prerequisites for building from a Git
-tree.  Afterward, proceed with the rest of the instructions using the
-distribution tarball.
+You must run this on a machine that has the tools listed in
+:ref:`general-build-reqs` as prerequisites for building from a Git tree.
+Afterward, proceed with the rest of the instructions using the distribution
+tarball.
 
 Now you have a distribution tarball, named something like
 ``openvswitch-x.y.z.tar.gz``.  Copy this file into the RPM sources directory,
@@ -135,6 +139,8 @@ where ``<target>`` is the name of an existing directory under
 contain some extra parts.  Once you have done this, verify the fix with the
 same procedure you used above to check for the problem.
 
+.. _rhel-building:
+
 Building
 --------
 
@@ -187,6 +193,8 @@ This produces an "kmod-openvswitch" RPM for each kernel variant, in this
 example: "kmod-openvswitch", "kmod-openvswitch-debug", and
 "kmod-openvswitch-kdump".
 
+.. _rhel-script-integrations:
+
 Red Hat Network Scripts Integration
 -----------------------------------
 
diff --git a/INSTALL.userspace.rst b/Documentation/intro/install/userspace.rst
similarity index 92%
rename from INSTALL.userspace.rst
rename to Documentation/intro/install/userspace.rst
index 1022355..0368527 100644
--- a/INSTALL.userspace.rst
+++ b/Documentation/intro/install/userspace.rst
@@ -22,7 +22,7 @@
       Avoid deeper levels because they do not render well.
 
 ===================================
-Open vSwitch Without Kernel Support
+Open vSwitch without Kernel Support
 ===================================
 
 Open vSwitch can operate, at a cost in performance, entirely in userspace,
@@ -42,9 +42,9 @@ Building and Installing
 -----------------------
 
 The requirements and procedure for building, installing, and configuring Open
-vSwitch are the same as those given in the `installation guide
-<INSTALL.rst>`__.  You may omit configuring, building, and installing the
-kernel module, and the related requirements.
+vSwitch are the same as those given in :doc:`general`. You may omit
+configuring, building, and installing the kernel module, and the related
+requirements.
 
 On Linux, the userspace switch additionally requires the kernel TUN/TAP driver
 to be available, either built into the kernel or loaded as a module.  If you
@@ -100,7 +100,7 @@ configuration might help.  See sysctl(7).::
 
     $ sysctl -w net.inet.ip.checkinterface=1
 
-Bug Reporting
--------------
+Reporting Bugs
+--------------
 
-Please report problems to bugs at openvswitch.org.
+Report problems to bugs at openvswitch.org.
diff --git a/INSTALL.Windows.rst b/Documentation/intro/install/windows.rst
similarity index 99%
rename from INSTALL.Windows.rst
rename to Documentation/intro/install/windows.rst
index 251cd10..eb55720 100644
--- a/INSTALL.Windows.rst
+++ b/Documentation/intro/install/windows.rst
@@ -171,8 +171,7 @@ Possible values for ``<target type>`` are: ``Debug`` and ``Release``
   You can directly use the Visual Studio 2013 IDE to compile the kernel
   datapath.  Open the ovsext.sln file in the IDE and build the solution.
 
-Refer to the `installation guide <INSTALL.rst>` for information on additional
-configuration options.
+Refer to :doc:`general` for information on additional configuration options.
 
 .. _windows-building:
 
diff --git a/INSTALL.XenServer.rst b/Documentation/intro/install/xenserver.rst
similarity index 96%
rename from INSTALL.XenServer.rst
rename to Documentation/intro/install/xenserver.rst
index 5f0fa41..c0f5e31 100644
--- a/INSTALL.XenServer.rst
+++ b/Documentation/intro/install/xenserver.rst
@@ -21,13 +21,13 @@
 
       Avoid deeper levels because they do not render well.
 
-===============================================
-How to Install Open vSwitch on Citrix XenServer
-===============================================
+================================
+Open vSwitch on Citrix XenServer
+================================
 
 This document describes how to build and install Open vSwitch on a Citrix
 XenServer host.  If you want to install Open vSwitch on a generic Linux or BSD
-host, see the `installation guide <INSTALL.rst>`__ instead.
+host, refer to :doc:`general` instead.
 
 Open vSwitch should work with XenServer 5.6.100 and later.  However, Open
 vSwitch requires Python 2.7 or later, so using Open vSwitch with XenServer 6.5
@@ -49,8 +49,8 @@ is the DDK VM available from Citrix.
 
    You cannot run this in the DDK VM, because it lacks tools that are necessary
    to bootstrap the Open vSwitch distribution.  Instead, you must run this on a
-   machine that has the tools listed in the installation guide <INSTALL.rst>`__
-   as prerequisites for building from a Git tree.
+   machine that has the tools listed in :ref:`general-install-reqs` as
+   prerequisites for building from a Git tree.
 
 2. Copy the distribution tarball into ``/usr/src/redhat/SOURCES`` inside
    the DDK VM.
diff --git a/FAQ.rst b/FAQ.rst
index a933c78..c5ae62f 100644
--- a/FAQ.rst
+++ b/FAQ.rst
@@ -486,7 +486,7 @@ Q: How do I configure a DPDK port as an access port?
 
     Finally, it is required that DPDK port names begin with ``dpdk``.
 
-    See `INSTALL.DPDK <INSTALL.DPDK.rst>`__ for more information on enabling
+    Refer to the `DPDK installation guide`_ for more information on enabling
     and using DPDK with Open vSwitch.
 
 Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all
@@ -794,7 +794,8 @@ very high.
       on the Port table in ovs-vswitchd.conf.db(5) for all the details.
 
       Configuration for DPDK-enabled interfaces is slightly less
-      straightforward: see `INSTALL.DPDK <INSTALL.DPDK.rst>`__.
+      straightforward. Refer to the `DPDK installation guide`_ for more
+      information.
 
     - Perhaps you don't actually need eth0 and eth1 to be on the same bridge.
       For example, if you simply want to be able to connect each of them to
@@ -862,8 +863,8 @@ port in the datapath?
     Linux GRE module is already loaded and blocking OVS (to confirm, check
     dmesg for errors regarding GRE registration). To fix this, unload all GRE
     modules that appear in lsmod as well as the OVS kernel module. You can then
-    reload the OVS module following the directions in the `installation guide
-    <INSTALL.rst>`__, which will ensure that dependencies are satisfied.
+    reload the OVS module following the directions in the `general installation
+    guide`_, which will ensure that dependencies are satisfied.
 
 Q: Open vSwitch does not seem to obey my packet filter rules.
 
@@ -2048,8 +2049,7 @@ Q: How do I implement a new OpenFlow message?
     ``lib/ofp-msgs.h``, following the existing pattern.  Then recompile and fix
     all of the new warnings, implementing new functionality for the new message
     as needed.  (If you configure with ``--enable-Werror``, as described in the
-    `installation guide <INSTALL.rst>`__, then it is impossible to miss any
-    warnings.)
+    `general installation guide`_, then it is impossible to miss any warnings.)
 
     If you need to add an OpenFlow vendor extension message for a vendor that
     doesn't yet have any extension messages, then you will also need to edit
@@ -2065,8 +2065,8 @@ Q: How do I add support for a new field or header?
     ``lib/nx-match.c`` to output your new field in OXM matches.  Then recompile
     and fix all of the new warnings, implementing new functionality for the new
     field or header as needed.  (If you configure with ``--enable-Werror``, as
-    described in the `installation guide <INSTALL.rst>`__, then it is impossible
-    to miss any warnings.)
+    described in the `general installation guide`_, then it is impossible to
+    miss any warnings.)
 
     If you want kernel datapath support for your new field, you also need to
     modify the kernel module for the operating systems you are interested in.
@@ -2085,9 +2085,12 @@ Q: How do I add support for a new OpenFlow action?
     ``lib/ofp-actions.c``, following the existing pattern.  Then recompile and
     fix all of the new warnings, implementing new functionality for the new
     action as needed.  (If you configure with ``--enable-Werror``, as described
-    in the `installation guide <INSTALL.rst>`__, then it is impossible to miss
-    any warnings.)
+    in the `general installation guide`_, then it is impossible to miss any
+    warnings.)
 
     If you need to add an OpenFlow vendor extension action for a vendor that
     doesn't yet have any extension actions, then you will also need to edit
     ``build-aux/extract-ofp-actions``.
+
+.. _general installation guide: Documentation/intro/install/general.rst
+.. _DPDK installation guide: Documentation/intro/install/dpdk.rst
diff --git a/Makefile.am b/Makefile.am
index 0036fec..df42149 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -70,21 +70,6 @@ docs = \
 	CONTRIBUTING.rst \
 	DESIGN.rst \
 	FAQ.rst \
-	INSTALL.rst \
-	INSTALL.Debian.rst \
-	INSTALL.Docker.rst \
-	INSTALL.DPDK-ADVANCED.rst \
-	INSTALL.DPDK.rst \
-	INSTALL.Fedora.rst \
-	INSTALL.KVM.rst \
-	INSTALL.Libvirt.rst \
-	INSTALL.NetBSD.rst \
-	INSTALL.RHEL.rst \
-	INSTALL.SELinux.rst \
-	INSTALL.SSL.rst \
-	INSTALL.XenServer.rst \
-	INSTALL.userspace.rst \
-	INSTALL.Windows.rst \
 	IntegrationGuide.rst \
 	MAINTAINERS.rst \
 	OPENFLOW.rst \
diff --git a/PORTING.rst b/PORTING.rst
index 33db41d..bae8cd9 100644
--- a/PORTING.rst
+++ b/PORTING.rst
@@ -141,13 +141,15 @@ Porting Strategies
 After a netdev provider has been implemented for a system's network devices,
 you may choose among three basic porting strategies.
 
+.. TODO(stephenfin): Update the link to the installation guide when this is
+   moved
+
 The lowest-effort strategy is to use the "userspace switch" implementation
 built into Open vSwitch.  This ought to work, without writing any more code, as
 long as the netdev provider that you implemented supports receiving packets.
 It yields poor performance, however, because every packet passes through the
-ovs-vswitchd process.  See the `userspace installation guide
-<INSTALL.userspace.rst>` for instructions on how to configure a userspace
-switch.
+ovs-vswitchd process.  See the `userspace installation guide` for instructions
+on how to configure a userspace switch.
 
 If the userspace switch is not the right choice for your port, then you will
 have to write more code.  You may implement either an "ofproto provider" or a
diff --git a/README.rst b/README.rst
index 715f969..c8227f8 100644
--- a/README.rst
+++ b/README.rst
@@ -73,36 +73,16 @@ Open vSwitch also provides some tools:
 What other documentation is available?
 --------------------------------------
 
-To install Open vSwitch on a regular Linux or FreeBSD host, please read the
-`installation guide <INSTALL.rst>`__. For specifics around installation on a
-specific platform, please see one of the below installation guides:
-
-- `Debian <INSTALL.Debian.rst>`__
-- `Fedora <INSTALL.Fedora.rst>`__
-- `RHEL <INSTALL.RHEL.rst>`__
-- `XenServer <INSTALL.XenServer.rst>`__
-- `Windows <INSTALL.Windows.rst>`__
-
-To use Open vSwitch...
-
-- ...with Docker on Linux, see `here <INSTALL.Docker.rst>`__.
-
-- ...with KVM on Linux, see `here <INSTALL.rst>`__ and `here
-  <INSTALL.KVM.rst>`__.
+.. TODO(stephenfin): Update with a link to the hosting site of the docs, once
+   we know where that is
 
-- ...with Libvirt, see `here <INSTALL.Libvirt.rst>`__.
-
-- ...without using a kernel module, see `here <INSTALL.userspace.rst>`__.
-
-- ...with DPDK, see `here <INSTALL.DPDK.rst>`__.
-
-- ...with SELinux, see `here <INSTALL.SELinux.rst>`__.
+To install Open vSwitch on a regular Linux or FreeBSD host, please read the
+`installation guide <Documentation/intro/install/general.rst>`__. For specifics
+around installation on a specific platform, refer to one of the `other
+installation guides <Documentation/intro/install/index.rst>`__
 
 For answers to common questions, refer to the `FAQ <FAQ.rst>`__.
 
-To learn how to set up SSL support for Open vSwitch, see `here
-<INSTALL.SSL.rst>`__.
-
 To learn about some advanced features of the Open vSwitch software switch, read
 the `tutorial <tutorial/tutorial.rst>`__.
 
diff --git a/debian/openvswitch-common.docs b/debian/openvswitch-common.docs
index c5612dd..27f5162 100644
--- a/debian/openvswitch-common.docs
+++ b/debian/openvswitch-common.docs
@@ -1,3 +1 @@
 FAQ.rst
-INSTALL.DPDK.rst
-README-native-tunneling.rst
diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in
index d1f33af..d70934a 100644
--- a/rhel/openvswitch-fedora.spec.in
+++ b/rhel/openvswitch-fedora.spec.in
@@ -481,8 +481,8 @@ fi
 %{_mandir}/man8/ovs-vswitchd.8*
 %{_mandir}/man8/ovs-parse-backtrace.8*
 %{_mandir}/man8/ovs-testcontroller.8*
-%doc COPYING DESIGN.rst INSTALL.SSL.rst NOTICE README.rst WHY-OVS.rst
-%doc FAQ.rst NEWS INSTALL.DPDK.rst rhel/README.RHEL.rst
+%doc COPYING DESIGN.rst NOTICE README.rst WHY-OVS.rst
+%doc FAQ.rst NEWS rhel/README.RHEL.rst
 /var/lib/openvswitch
 /var/log/openvswitch
 %ghost %attr(755,root,root) %{_rundir}/openvswitch
diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in
index 9f6549a..d03588c 100644
--- a/rhel/openvswitch.spec.in
+++ b/rhel/openvswitch.spec.in
@@ -248,8 +248,8 @@ exit 0
 /usr/share/openvswitch/scripts/sysconfig.template
 /usr/share/openvswitch/vswitch.ovsschema
 /usr/share/openvswitch/vtep.ovsschema
-%doc COPYING DESIGN.rst INSTALL.SSL.rst NOTICE README.rst WHY-OVS.rst FAQ.rst NEWS
-%doc INSTALL.DPDK.rst rhel/README.RHEL.rst README-native-tunneling.rst
+%doc COPYING DESIGN.rst NOTICE README.rst WHY-OVS.rst FAQ.rst NEWS
+%doc rhel/README.RHEL.rst README-native-tunneling.rst
 /var/lib/openvswitch
 /var/log/openvswitch
 
diff --git a/tutorial/ovn-tutorial.rst b/tutorial/ovn-tutorial.rst
index 8d9fc1a..bb5f620 100644
--- a/tutorial/ovn-tutorial.rst
+++ b/tutorial/ovn-tutorial.rst
@@ -873,11 +873,12 @@ of what the resulting OpenFlow flows look like.
 Container Ports
 ---------------
 
+.. TODO(stephenfin): Update Docker link when this is moved.
+
 OVN supports containers running directly on the hypervisors and running
 containers inside VMs. This example shows how OVN supports network
 virtualization to containers when run inside VMs. Details about how to use
-docker containers in OVS can be found in the `Docker installlation guide
-<../INSTALL.Docker.rst>`__.
+docker containers in OVS can be found in the `Docker installlation guide`.
 
 To support container traffic created inside a VM and to distinguish network
 traffic coming from different container vifs, for each container a logical port
diff --git a/tutorial/tutorial.rst b/tutorial/tutorial.rst
index fab6350..422bc0d 100644
--- a/tutorial/tutorial.rst
+++ b/tutorial/tutorial.rst
@@ -54,6 +54,8 @@ hardware or even supervisor privilege on your system.  Instead, we will use a
 script called ``ovs-sandbox``, which accompanies the tutorial, that constructs
 a software simulated network environment based on Open vSwitch.
 
+.. TODO(stephenfin): Update installation guide link when this is moved.
+
 You can use ``ovs-sandbox`` three ways:
 
 * If you have already installed Open vSwitch on your system, then you should be
@@ -61,9 +63,9 @@ You can use ``ovs-sandbox`` three ways:
 
 * If you have not installed Open vSwitch (and you do not want to install it),
   then you can build Open vSwitch according to the instructions in the
-  `installation guide <INSTALL.rst>`__, without installing it.  Then run
-  ``./ovs-sandbox -b DIRECTORY`` from this directory, substituting the Open
-  vSwitch build directory for ``DIRECTORY``.
+  `installation guide`, without installing it.  Then run ``./ovs-sandbox -b
+  DIRECTORY`` from this directory, substituting the Open vSwitch build
+  directory for ``DIRECTORY``.
 
 * As a slight variant on the latter, you can run ``make sandbox`` from an Open
   vSwitch build directory.
diff --git a/utilities/automake.mk b/utilities/automake.mk
index 014e477..2590dc0 100644
--- a/utilities/automake.mk
+++ b/utilities/automake.mk
@@ -37,11 +37,9 @@ noinst_SCRIPTS += utilities/ovs-sim
 
 utilities/ovs-lib: $(top_builddir)/config.status
 
-docs += utilities/ovs-command-bashcomp.INSTALL.rst
 EXTRA_DIST += \
 	utilities/ovs-appctl-bashcomp.bash \
 	utilities/ovs-check-dead-ifs.in \
-	utilities/ovs-command-bashcomp.INSTALL.rst \
 	utilities/ovs-ctl.in \
 	utilities/ovs-dev.py \
 	utilities/ovs-docker \
diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8
index cd7c267..1fe0a3c 100644
--- a/utilities/ovs-ctl.8
+++ b/utilities/ovs-ctl.8
@@ -502,5 +502,4 @@ distribution are good examples of how to use \fBovs\-ctl\fR.
 .
 .SH "SEE ALSO"
 .
-\fBREADME.rst\fR, \fBINSTALL.Linux.rst\fR, \fBovsdb\-server\fR(8),
-\fBovs\-vswitchd\fR(8).
+\fBREADME.rst\fR, \fBovsdb\-server\fR(8), \fBovs\-vswitchd\fR(8).
diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
index 4128801..1917906 100644
--- a/utilities/ovs-vsctl.8.in
+++ b/utilities/ovs-vsctl.8.in
@@ -399,9 +399,9 @@ Sets the configured failure mode.
 These commands manipulate the \fBmanager_options\fR column in the
 \fBOpen_vSwitch\fR table and rows in the \fBManagers\fR table.  When
 \fBovsdb\-server\fR is configured to use the \fBmanager_options\fR column for
-OVSDB connections (as described in \fBINSTALL.Linux\fR and in the startup
-scripts provided with Open vSwitch), this allows the administrator to use
-\fBovs\-vsctl\fR to configure database connections.
+OVSDB connections (as described in the startup scripts provided with
+Open vSwitch), this allows the administrator to use \fBovs\-vsctl\fR to
+configure database connections.
 .
 .IP "\fBget\-manager\fR"
 Prints the configured manager(s).
diff --git a/vswitchd/ovs-vswitchd.8.in b/vswitchd/ovs-vswitchd.8.in
index c745dbc..fc19f3b 100644
--- a/vswitchd/ovs-vswitchd.8.in
+++ b/vswitchd/ovs-vswitchd.8.in
@@ -67,9 +67,8 @@ to modify datapaths when \fBovs\-vswitchd\fR is running can interfere with
 its operation.  (\fBovs\-dpctl\fR may still be useful for diagnostics.)
 .PP
 An Open vSwitch datapath kernel module must be loaded for \fBovs\-vswitchd\fR
-to be useful.  Please refer to the \fBINSTALL.Linux\fR file included in the
-Open vSwitch distribution for instructions on how to build and load
-the Open vSwitch kernel module.
+to be useful.  Refer to the documentation for instructions on how to build and
+load the Open vSwitch kernel module.
 .PP
 .SH OPTIONS
 .IP "\fB\-\-mlockall\fR"
@@ -85,7 +84,7 @@ unavailable or unsuccessful.
 .
 .SS "DPDK Options"
 For details on initializing the \fBovs\-vswitchd\fR DPDK datapath,
-refer to INSTALL.DPDK.rst or \fBovs\-vswitchd.conf.db\fR(5) for
+refer to the documentation or \fBovs\-vswitchd.conf.db\fR(5) for
 details.
 .SS "Daemon Options"
 .ds DD \
@@ -348,5 +347,4 @@ time linear in the number of flows.
 .
 .SH "SEE ALSO"
 .BR ovs\-appctl (8),
-.BR ovsdb\-server (1),
-\fBINSTALL.Linux\fR in the Open vSwitch distribution.
+.BR ovsdb\-server (1).
diff --git a/vtep/README.ovs-vtep.rst b/vtep/README.ovs-vtep.rst
index 75f03d0..668ee08 100644
--- a/vtep/README.ovs-vtep.rst
+++ b/vtep/README.ovs-vtep.rst
@@ -36,13 +36,12 @@ The VTEP emulator is a Python script that invokes calls to tools like vtep-ctl
 and ovs-vsctl. It is only useful when Open vSwitch daemons like ovsdb-server
 and ovs-vswitchd are running and installed. To do this, either:
 
-- Follow the instructions in the `installation guide <..INSTALL.rst>`__ (don't
+- Follow the instructions in ``Documentation/intro/install/general`` (don't
   start any daemons yet).
 
-- Follow the instructions in `Debian installation guide
-  <../INSTALL.Debian.rst>`__ and then install the ``openvswitch-vtep`` package
-  (if operating on a debian based machine). This will automatically start the
-  daemons.
+- Follow the instructions in ``Documentation/intro/install/debian`` and then
+  install the ``openvswitch-vtep`` package (if operating on a debian based
+  machine).  This will automatically start the daemons.
 
 Design
 ------
@@ -152,9 +151,9 @@ using the debian packages as mentioned in step 2 of the "Requirements" section.
        $ vtep-ctl add-ps br0
        $ vtep-ctl set Physical_Switch br0 tunnel_ips=10.2.2.1
 
-6. Start the VTEP emulator. If you installed the components following the
-   `installation guide <../INSTALL.rst>`__ file, run the following from the
-   same directory as this README:
+6. Start the VTEP emulator. If you installed the components following
+   ``Documentation/intro/install/general``, run the following from the same
+   directory as this README:
 
    ::
 
diff --git a/vtep/vtep-ctl.8.in b/vtep/vtep-ctl.8.in
index e0f49a7..1901356 100644
--- a/vtep/vtep-ctl.8.in
+++ b/vtep/vtep-ctl.8.in
@@ -325,9 +325,9 @@ List the remote MAC bindings for \fIlswitch\fR, one per line.
 These commands manipulate the \fBmanagers\fR column in the \fBGlobal\fR
 table and rows in the \fBManagers\fR table.  When \fBovsdb\-server\fR is
 configured to use the \fBmanagers\fR column for OVSDB connections (as
-described in \fBINSTALL.Linux\fR and in the startup scripts provided
-with Open vSwitch), this allows the administrator to use \fBvtep\-ctl\fR
-to configure database connections.
+described in the startup scripts provided with Open vSwitch), this
+allows the administrator to use \fBvtep\-ctl\fR to configure database
+connections.
 .
 .IP "\fBget\-manager\fR"
 Prints the configured manager(s).
-- 
2.9.3



More information about the dev mailing list