doc: Populate 'topics' section

There are many docs that don't need to kept at the top level, along
with many more hidden in random folders. Move them all.

This also allows us to add the '-W' flag to Sphinx, ensuring unindexed
docs result in build failures.

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>

Author: stephenfin

Documentation/automake.mk

@@ -1,6 +1,5 @@
 docs += \
-	Documentation/group-selection-method-property.txt \
-	Documentation/OVSDB-replication.rst
+	Documentation/group-selection-method-property.txt
 
 EXTRA_DIST += \
 	Documentation/_static/logo.png \
@@ -22,6 +21,16 @@ EXTRA_DIST += \
 	Documentation/intro/install/xenserver.rst \
 	Documentation/tutorials/index.rst \
 	Documentation/topics/index.rst \
+	Documentation/topics/bonding.rst \
+	Documentation/topics/datapath.rst \
+	Documentation/topics/design.rst \
+	Documentation/topics/dpdk.rst \
+	Documentation/topics/high-availability.rst \
+	Documentation/topics/integration.rst \
+	Documentation/topics/openflow.rst \
+	Documentation/topics/ovsdb-replication.rst \
+	Documentation/topics/porting.rst \
+	Documentation/topics/windows.rst \
 	Documentation/howto/index.rst \
 	Documentation/howto/docker.rst \
 	Documentation/howto/kvm.rst \
@@ -58,8 +67,7 @@ SPHINXBUILDDIR = $(srcdir)/Documentation/_build
 # Internal variables.
 PAPEROPT_a4 = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-# TODO(stephenfin): Add '-W' flag here once we've integrated required docs
-ALLSPHINXOPTS = -d $(SPHINXBUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSRCDIR)
+ALLSPHINXOPTS = -W -d $(SPHINXBUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSRCDIR)
 
 .PHONY: htmldocs
 htmldocs:

Documentation/howto/openstack-containers.rst

@@ -45,10 +45,10 @@ example.
 
 * When VM-A is created on a hypervisor, its VIF gets added to the Open vSwitch
   integration bridge.  This creates a row in the Interface table of the
-  ``Open_vSwitch`` database.  As explained in the `integration guide`, the
-  vif-id associated with the VM network interface gets added in the
-  ``external_ids:iface-id`` column of the newly created row in the Interface
-  table.
+  ``Open_vSwitch`` database.  As explained in the :doc:`integration guide
+  </topics/integration>`, the vif-id associated with the VM network interface
+  gets added in the ``external_ids:iface-id`` column of the newly created row
+  in the Interface table.
 
 * Since VM-A belongs to a logical network, it gets an IP address.  This IP
   address is used to spawn containers (either manually or through container

Documentation/intro/install/netbsd.rst

@@ -58,4 +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 :doc:`userspace` and the `porting guide`.
+sense described in :doc:`userspace` and :doc:`/topics/porting`.

vswitchd/INTERNALS.rst Documentation/topics/bonding.rst

@@ -21,21 +21,9 @@
 
       Avoid deeper levels because they do not render well.
 
-======================
-ovs-vswitchd Internals
-======================
-
-This document describes some of the internals of the ovs-vswitchd process.  It
-is not complete.  It tends to be updated on demand, so if you have questions
-about the vswitchd implementation, ask them and perhaps we'll add some
-appropriate documentation here.
-
-Most of the ovs-vswitchd implementation is in ``vswitchd/bridge.c``, so code
-references below should be assumed to refer to that file except as otherwise
-specified.
-
+=======
 Bonding
--------
+=======
 
 Bonding allows two or more interfaces (the "slaves") to share network traffic.
 From a high-level point of view, bonded interfaces act like a single port, but
@@ -55,8 +43,15 @@ Ethernet source address.  This is useful only if the traffic over the bond has
 multiple Ethernet source addresses, for example if network traffic from
 multiple VMs are multiplexed over the bond.
 
+.. note::
+
+   Most of the ovs-vswitchd implementation is in ``vswitchd/bridge.c``, so code
+   references below should be assumed to refer to that file except as otherwise
+   specified.
+
+
 Enabling and Disabling Slaves
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 When a bond is created, a slave is initially enabled or disabled based on
 whether carrier is detected on the NIC (see ``iface_create()``).  After that, a
@@ -86,7 +81,7 @@ connected to a physical switch; vswitchd should probably provide a way to
 disable or configure it in other scenarios.)
 
 Bond Packet Input
-~~~~~~~~~~~~~~~~~
+-----------------
 
 Bonding accepts unicast packets on any bond slave.  This can occasionally cause
 packet duplication for the first few packets sent to a given MAC, if the
@@ -118,7 +113,7 @@ remaining slave whose interface name is first alphabetically, but this is by no
 means guaranteed.
 
 Bond Packet Output
-~~~~~~~~~~~~~~~~~~
+------------------
 
 When a packet is sent out a bond port, the bond slave actually used is selected
 based on the packet's source MAC and VLAN tag (see ``choose_output_iface()``).
@@ -143,12 +138,12 @@ Currently, "significantly more loaded" means that H must carry at least 1 Mbps
 more traffic, and that traffic must be at least 3% greater than L's.
 
 Bond Balance Modes
-~~~~~~~~~~~~~~~~~~
+------------------
 
 Each bond balancing mode has different considerations, described below.
 
 LACP Bonding
-++++++++++++
+~~~~~~~~~~~~
 
 LACP bonding requires the remote switch to implement LACP, but it is otherwise
 very simple in that, after LACP negotiation is complete, there is no need for
@@ -169,7 +164,7 @@ configuration is complete. An option "lacp-fallback-ab" exists to provide such
 behavior on openvswitch.
 
 Active Backup Bonding
-+++++++++++++++++++++
+~~~~~~~~~~~~~~~~~~~~~
 
 Active Backup bonds send all traffic out one "active" slave until that slave
 becomes unavailable.  Since they are significantly less complicated than SLB
@@ -178,7 +173,7 @@ the only bond mode which supports attaching each slave to a different upstream
 switch.
 
 SLB Bonding
-+++++++++++
+~~~~~~~~~~~
 
 SLB bonding allows a limited form of load balancing without the remote switch's
 knowledge or cooperation.  The basics of SLB are simple.  SLB assigns each
@@ -241,4 +236,3 @@ SLB bonding has the following complications:
    for a MAC+VLAN from which a gratuitous ARP was received from a non-SLB bond
    port.  For 5 seconds, a locked MAC learning table entry will not be updated
    based on a gratuitous ARP received on a SLB bond.
-

datapath/README.rst Documentation/topics/datapath.rst

@@ -0,0 +1,28 @@
+..
+      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.
+
+================
+DPDK Integration
+================
+
+**TODO**

DESIGN.rst Documentation/topics/design.rst

@@ -32,3 +32,18 @@ that way.
 
 .. toctree::
    :maxdepth: 2
+
+   design
+   datapath
+   integration
+   porting
+   openflow
+   bonding
+   ovsdb-replication
+   dpdk
+   windows
+
+.. toctree::
+   :maxdepth: 2
+
+   high-availability

Documentation/topics/dpdk.rst

@@ -28,10 +28,10 @@ Integration Guide for Centralized Control
 This document describes how to integrate Open vSwitch onto a new platform to
 expose the state of the switch and attached devices for centralized control.
 (If you are looking to port the switching components of Open vSwitch to a new
-platform, please see the PORTING document.)  The focus of this guide is on
-hypervisors, but many of the interfaces are useful for hardware switches, as
-well.  The XenServer integration is the most mature implementation, so most of
-the examples are drawn from it.
+platform, refer to :doc:`porting`)  The focus of this guide is on hypervisors,
+but many of the interfaces are useful for hardware switches, as well.  The
+XenServer integration is the most mature implementation, so most of the
+examples are drawn from it.
 
 The externally visible interface to this integration is platform-agnostic.  We
 encourage anyone who integrates Open vSwitch to use the same interface, because
@@ -204,11 +204,11 @@ contents. At all times, the data can be transacted only from the active server.
 When the active server dies for some reason, entire OVN operations will be
 stalled.
 
-`Pacemaker <http://clusterlabs.org/pacemaker.html>`_ is a cluster resource
+`Pacemaker <http://clusterlabs.org/pacemaker.html>`__ is a cluster resource
 manager which can manage a defined set of resource across a set of clustered
 nodes. Pacemaker manages the resource with the help of the resource agents.
-One among the resource agent is
-`OCF <http://www.linux-ha.org/wiki/OCF_Resource_Agents>`_
+One among the resource agent is `OCF
+<http://www.linux-ha.org/wiki/OCF_Resource_Agents>`__
 
 OCF is nothing but a shell script which accepts a set of actions and returns an
 appropriate status code.
@@ -217,48 +217,41 @@ With the help of the OCF resource agent ovn/utilities/ovndb-servers.ocf, one
 can defined a resource for the pacemaker such that pacemaker will always
 maintain one running active server at any time.
 
-After creating a pacemaker cluster, use the following commands to create
-one active and multiple backup servers for OVN databases.
+After creating a pacemaker cluster, use the following commands to create one
+active and multiple backup servers for OVN databases::
 
-::
-
-    pcs resource create ovndb_servers ocf:ovn:ovndb-servers \
+    $ pcs resource create ovndb_servers ocf:ovn:ovndb-servers \
          master_ip=x.x.x.x \
          ovn_ctl=<path of the ovn-ctl script> \
          op monitor interval="10s" \
          op monitor role=Master interval="15s"
-
-    pcs resource master ovndb_servers-master ovndb_servers \
+    $ pcs resource master ovndb_servers-master ovndb_servers \
         meta notify="true"
 
-The `master_ip` and `ovn_ctl` are the parameters that will be used by the
-OCF script. `ovn_ctl` is optional, if not given, it assumes a default value of
+The `master_ip` and `ovn_ctl` are the parameters that will be used by the OCF
+script. `ovn_ctl` is optional, if not given, it assumes a default value of
 /usr/share/openvswitch/scripts/ovn-ctl. `master_ip` is the IP address on which
 the active database server is expected to be listening.
 
-Whenever the active server dies, pacemaker is responsible to promote one of
-the backup servers to be active. Both ovn-controller and ovn-northd needs the
+Whenever the active server dies, pacemaker is responsible to promote one of the
+backup servers to be active. Both ovn-controller and ovn-northd needs the
 ip-address at which the active server is listening. With pacemaker changing the
 node at which the active server is run, it is not efficient to instruct all the
 ovn-controllers and the ovn-northd to listen to the latest active server's
 ip-address.
 
 This problem can be solved by using a native ocf resource agent
-`ocf:heartbeat:IPaddr2`. The IPAddr2 resource agent is just a resource with an
-ip-address. When we colocate this resource with the active server, pacemaker
+``ocf:heartbeat:IPaddr2``. The IPAddr2 resource agent is just a resource with
+an ip-address. When we colocate this resource with the active server, pacemaker
 will enable the active server to be connected with a single ip-address all the
 time. This is the ip-address that needs to be given as the parameter while
 creating the `ovndb_servers` resource.
 
 Use the following command to create the IPAddr2 resource and colocate it
-with the active server.
+with the active server::
 
-::
-
-    pcs resource create VirtualIP ocf:heartbeat:IPaddr2 ip=x.x.x.x \
+    $ pcs resource create VirtualIP ocf:heartbeat:IPaddr2 ip=x.x.x.x \
         op monitor interval=30s
-
-    pcs constraint order VirtualIP then ovndb_servers-master
-
-    pcs constraint colocation add master ovndb_servers-master with VirtualIP \
+    $ pcs constraint order VirtualIP then ovndb_servers-master
+    $ pcs constraint colocation add master ovndb_servers-master with VirtualIP \
         score=INFINITY

ovn/OVN-GW-HA.rst Documentation/topics/high-availability.rst

@@ -395,21 +395,25 @@ How to contribute
 If you plan to contribute code for a feature, please let everyone know on
 ovs-dev before you start work.  This will help avoid duplicating work.
 
-Please consider the following:
+Consider the following:
 
-* Testing.  Please test your code.
+* Testing.
 
-* Unit tests.  Please consider writing some.  The tests directory has many
-  examples that you can use as a starting point.
+  Please test your code.
 
-* ovs-ofctl.  If you add a feature that is useful for some ovs-ofctl command
-  then you should add support for it there.
+* Unit tests.
 
-* Documentation.  If you add a user-visible feature, then you should document
-  it in the appropriate manpage and mention it in NEWS as well.
+  Consider writing some.  The tests directory has many examples that you can
+  use as a starting point.
 
-* Coding style (see the `coding style guide <CodingStyle.rst>`__ file at the top
-  of the source tree).
+* ovs-ofctl.
 
-* The `patch submission guidelines <CONTRIBUTING.rst>`__.  I recommend using
-  "git send-email", which automatically follows a lot of those guidelines.
+  If you add a feature that is useful for some ovs-ofctl command then you
+  should add support for it there.
+
+* Documentation.
+
+  If you add a user-visible feature, then you should document it in the
+  appropriate manpage and mention it in NEWS as well.
+
+Refer to :doc:`/internals/contributing/index` for more information.

Documentation/topics/index.rst

@@ -141,14 +141,11 @@ 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` for instructions
+ovs-vswitchd process. Refer to :doc:`/intro/install/userspace` for instructions
 on how to configure a userspace switch.
 
 If the userspace switch is not the right choice for your port, then you will

IntegrationGuide.rst Documentation/topics/integration.rst

@@ -79,8 +79,9 @@ Q: Does Open vSwitch only work on Linux?
 
 Q: What's involved with porting Open vSwitch to a new platform or switching ASIC?
 
-    A: The `porting document <PORTING.rst>`__ describes how one would go about
-    porting Open vSwitch to a new operating system or hardware platform.
+    A: The `porting document <Documentation/development-guide/porting.rst>`__
+    describes how one would go about porting Open vSwitch to a new operating
+    system or hardware platform.
 
 Q: Why would I use Open vSwitch instead of the Linux bridge?
 
@@ -1588,9 +1589,10 @@ Q: What versions of OpenFlow does Open vSwitch support?
     (Open vSwitch 2.2 had an experimental implementation of OpenFlow 1.4 that
     could cause crashes.  We don't recommend enabling it.)
 
-    The `OpenFlow guide <OPENFLOW.rst>`__ tracks support for OpenFlow 1.1 and
-    later features.  When support for OpenFlow 1.4 and 1.5 is solidly
-    implemented, Open vSwitch will enable those version by default.
+    The `OpenFlow guide <Documentation/development-guide/openflow.rst>`__
+    tracks support for OpenFlow 1.1 and later features.  When support for
+    OpenFlow 1.4 and 1.5 is solidly implemented, Open vSwitch will enable those
+    version by default.
 
 Q: Does Open vSwitch support MPLS?
 
@@ -1651,8 +1653,8 @@ going through.
     greater than 65535 (the maximum priority that can be set with
     OpenFlow).
 
-    The DESIGN file at the top level of the Open vSwitch source
-    distribution describes the in-band model in detail.
+    The ``Documentation/topics/design`` doc describes the in-band model in
+    detail.
 
     If your controllers are not actually in-band (e.g. they are on
     localhost via 127.0.0.1, or on a separate network), then you should

OPENFLOW.rst Documentation/topics/openflow.rst

@@ -68,12 +68,8 @@ PYCOV_CLEAN_FILES = build-aux/check-structs,cover
 docs = \
 	AUTHORS.rst \
 	CONTRIBUTING.rst \
-	DESIGN.rst \
 	FAQ.rst \
-	IntegrationGuide.rst \
 	MAINTAINERS.rst \
-	OPENFLOW.rst \
-	PORTING.rst \
 	README.rst \
 	WHY-OVS.rst
 EXTRA_DIST = \