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>

5 files changed, 9 insertions, 10 deletions

diff --git a/lib/dpif.h b/lib/dpif.h
index e69087dee..40ffe29e7 100644
--- a/lib/dpif.h
+++ b/lib/dpif.h
@@ -113,9 +113,8 @@
  *
  *      In Open vSwitch userspace, "struct flow" is the typical way to describe
  *      a flow, but the datapath interface uses a different data format to
- *      allow ABI forward- and backward-compatibility.  datapath/README.rst
- *      describes the rationale and design.  Refer to OVS_KEY_ATTR_* and
- *      "struct ovs_key_*" in include/odp-netlink.h for details.
+ *      allow ABI forward- and backward-compatibility.  Refer to OVS_KEY_ATTR_*
+ *      and "struct ovs_key_*" in include/odp-netlink.h for details.
  *      lib/odp-util.h defines several functions for working with these flows.
  *
  *    - A "mask" that, for each bit in the flow, specifies whether the datapath
diff --git a/lib/mac-learning.c b/lib/mac-learning.c
index 57b81f418..44c49622b 100644
--- a/lib/mac-learning.c
+++ b/lib/mac-learning.c
@@ -410,9 +410,9 @@ update_learning_table__(struct mac_learning *ml, struct eth_addr src,
          * reflected packets, so we lock each entry for which a gratuitous ARP
          * packet was received over a non-bond interface and refrain from
          * learning from gratuitous ARP packets that arrive over bond
-         * interfaces for this entry while the lock is in effect.  See
-         * vswitchd/INTERNALS.rst for more in-depth discussion on this
-         * topic. */
+         * interfaces for this entry while the lock is in effect. Refer to the
+         * 'ovs-vswitch Internals' document for more in-depth discussion on
+         * this topic. */
         if (!is_bond) {
             mac_entry_set_grat_arp_lock(mac);
         } else if (mac_entry_is_grat_arp_locked(mac)) {
diff --git a/lib/mac-learning.h b/lib/mac-learning.h
index e42781500..ee14185d9 100644
--- a/lib/mac-learning.h
+++ b/lib/mac-learning.h
@@ -46,8 +46,8 @@
  *
  * Second, the implementation has the ability to "lock" a MAC table entry
  * updated by a gratuitous ARP.  This is a simple feature but the rationale for
- * it is complicated.  Please refer to the description of SLB bonding in
- * vswitchd/INTERNALS.rst for an explanation.
+ * it is complicated.  Refer to the description of SLB bonding in the
+ * 'ovs-vswitchd Internals' guide for an explanation.
  *
  * Third, the implementation expires entries that are idle for longer than a
  * configurable amount of time.  This is implemented by keeping all of the
diff --git a/lib/netdev.h b/lib/netdev.h
index bad28c4c1..a667fe35f 100644
--- a/lib/netdev.h
+++ b/lib/netdev.h
@@ -30,7 +30,7 @@ extern "C" {
  *
  * Every port on a switch must have a corresponding netdev that must minimally
  * support a few operations, such as the ability to read the netdev's MTU.
- * The PORTING file at the top of the source tree has more information in the
+ * The Porting section of the documentation has more information in the
  * "Writing a netdev Provider" section.
  *
  * Thread-safety
diff --git a/lib/ofp-util.c b/lib/ofp-util.c
index 899cfe388..b9efd32ee 100644
--- a/lib/ofp-util.c
+++ b/lib/ofp-util.c
@@ -5679,7 +5679,7 @@ ofputil_encode_table_config(enum ofputil_table_miss miss,
                             enum ofp_version version)
 {
     uint32_t config = 0;
-    /* See the section "OFPTC_* Table Configuration" in DESIGN.rst for more
+    /* Search for "OFPTC_* Table Configuration" in the documentation for more
      * information on the crazy evolution of this field. */
     switch (version) {
     case OFP10_VERSION: