doc: improve table-of-contents organization

The current TOC organization is not really following Sphinx best
practices and is resulting in a jumble of articles showing up in the
sidebar.

This change primarily organizes existing articles into three major
sections:

* Introduction
  - Contains system requirements, architecture & design, installation,
    basic setup
* Basics
  - Covers basic commands, concepts, and some random things that don't
    fit elsewhere
* Protocols
  - Contains all protocol documentation, and other miscellaneous daemon
    docs such as those on Zebra, watchfrr, mgmtd, etc.

The appendix has been left as is, but the TOC now has a caption which
has the effect of adding a section separator in the nav sidebar.

In order to make the new structure make sense:

* Some content has been lifted up from the "Overview" page into the
  index page
* Most content has been pushed down from the "Overview" page into the
  "About" page (new)
* BFD's page is now titled "BFD" for consistencty; it was the only one
  that had the full protocol name written out in the title

And a couple drivebys:
* BFD's intro description paragraph was rewritten to make more sense
* Old language stating that we publish platform packages on the Github
  releases page was removed
* References to source building instructions were consolidated into that
  section

Signed-off-by: Quentin Young <[email protected]>

doc/user/overview.rst → doc/user/about.rst

@@ -1,47 +1,8 @@
 .. _overview:
 
-********
-Overview
-********
-
-`FRR`_ is a fully featured, high performance, free software IP routing suite.
-
-FRR implements all standard routing protocols such as BGP, RIP, OSPF, IS-IS and
-more (see :ref:`feature-matrix`), as well as many of their extensions.
-
-FRR is a high performance suite written primarily in C. It can easily handle
-full Internet routing tables and is suitable for use on hardware ranging from
-cheap SBCs to commercial grade routers. It is actively used in production by
-hundreds of companies, universities, research labs and governments.
-
-FRR is distributed under GPLv2, with development modeled after the Linux
-kernel. Anyone may contribute features, bug fixes, tools, documentation
-updates, or anything else.
-
-FRR is a fork of `Quagga <http://www.quagga.net/>`_.
-
-.. _how-to-get-frr:
-
-How to get FRR
-==============
-
-The official FRR website is located at |PACKAGE_URL| and contains further
-information, as well as links to additional resources.
-
-Several distributions provide packages for FRR. Check your distribution's
-repositories to find out if a suitable version is available.
-
-Up-to-date Debian & Redhat packages are available at https://deb.frrouting.org/
-& https://rpm.frrouting.org/ respectively.
-
-For instructions on installing from source, refer to the
-`developer documentation <http://docs.frrouting.org/projects/dev-guide/en/latest/>`_.
-
-
-.. _about-frr:
-
+*********
 About FRR
-=========
+*********
 
 FRR provides IP routing services. Its role in a networking stack is to exchange
 routing information with other routers, make routing and policy decisions, and
@@ -55,11 +16,8 @@ light L2 functionality as well, but this is mostly left to the platform. This
 makes it suitable for deployments ranging from small home networks with static
 routes to Internet exchanges running full Internet tables.
 
-FRR runs on all modern \*NIX operating systems, including Linux and the BSDs.
-Feature support varies by platform; see the :ref:`feature-matrix`.
-
 System Requirements
--------------------
+===================
 
 System resources needed by FRR are highly dependent on workload. Routing
 software performance is particularly susceptible to external factors such as:
@@ -86,8 +44,8 @@ information with peers about how to forward packets. Forwarding plane
 performance largely depends on choice of NIC / ASIC.
 
 
-System Architecture
--------------------
+Architecture
+============
 
 .. index::
    pair: architecture; FRR
@@ -146,9 +104,8 @@ routing stack.
 
 .. _supported-platforms:
 
-Supported Platforms
--------------------
-
+Platform Support
+================
 
 Currently FRR supports GNU/Linux and BSD. Porting FRR to other platforms is not
 too difficult as platform dependent code should be mostly limited to the

doc/user/basics.rst

@@ -0,0 +1,23 @@
+.. _basics:
+
+######
+Basics
+######
+
+.. toctree::
+   :maxdepth: 2
+
+   basic
+   extlog
+   vtysh
+   grpc
+   filter
+   routemap
+   affinitymap
+   ipv6
+   kernel
+   snmp
+   scripting
+   nexthop_groups
+
+

doc/user/bfd.rst

@@ -1,12 +1,19 @@
 .. _bfd:
 
-**********************************
-Bidirectional Forwarding Detection
-**********************************
+***
+BFD
+***
 
-:abbr:`BFD (Bidirectional Forwarding Detection)` stands for
-Bidirectional Forwarding Detection and it is described and extended by
-the following RFCs:
+:abbr:`BFD (Bidirectional Forwarding Detection)` is:
+
+  a protocol intended to detect faults in the bidirectional path between two
+  forwarding engines, including interfaces, data link(s), and to the extent
+  possible the forwarding engines themselves, with potentially very low
+  latency.
+
+  -- :rfc:`5880`
+
+It is described and extended by the following RFCs:
 
 * :rfc:`5880`
 * :rfc:`5881`

doc/user/index.rst

@@ -1,80 +1,31 @@
 FRRouting User Guide
 ====================
 
-############
-Introduction
-############
+FRR is a fully featured, high performance, free software IP routing suite.  It
+implements all standard routing protocols such as BGP, RIP, OSPF, IS-IS and
+more (see :ref:`feature-matrix`), as well as many of their extensions. It can
+handle full Internet routing tables and is suitable for use on hardware ranging
+from cheap SBCs to commercial grade routers, and is actively used in production
+by hundreds of companies, universities, research labs and governments.
 
-.. _introduction:
-.. toctree::
-   :maxdepth: 2
-
-   overview
-   installation
-   setup
-
-######
-Basics
-######
+FRR runs on all modern \*NIX operating systems, including Linux and the BSDs.
+Feature support varies by platform; see the :ref:`feature-matrix`.
 
-.. _basics:
-.. toctree::
-   :maxdepth: 2
+FRR is distributed under GPLv2, with development modeled after the Linux
+kernel. Anyone may contribute features, bug fixes, tools, documentation
+updates, or anything else.
 
-   basic
-   extlog
-   vtysh
-   grpc
-   filter
-   routemap
-   affinitymap
-   ipv6
-   kernel
-   snmp
-   scripting
-   nexthop_groups
-.. modules
+FRR is a fork of `Quagga <http://www.quagga.net/>`_.
 
-#########
-Protocols
-#########
-
-.. _protocols:
 .. toctree::
    :maxdepth: 2
 
-   zebra
-   bfd
-   bgp
-   babeld
-   fabricd
-   ldpd
-   eigrpd
-   evpn
-   isisd
-   nhrpd
-   ospfd
-   ospf6d
-   pathd
-   pim
-   pimv6
-   pbr
-   ripd
-   ripngd
-   sharp
-   static
-   vnc
-   vrrp
-   bmp
-   watchfrr
-   mgmtd
-
-########
-Appendix
-########
+   introduction
+   basics
+   protocols
 
-.. _appendix:
 .. toctree::
+   :caption: Appendix
    :maxdepth: 2
 
    bugs

doc/user/installation.rst

@@ -3,22 +3,25 @@
    single: Installing FRR
    single: Building FRR
 
-.. _installation:
-
 Installation
 ============
 
-This section covers the basics of building, installing and setting up FRR.
+This section covers the basics of building, installing and setting up
+FRR.
 
+The official FRR website is located at |PACKAGE_URL| and contains further
+information, as well as links to additional resources.
 
 From Packages
 -------------
 
-The project publishes packages for Red Hat, Centos, Debian and Ubuntu on the
-`GitHub releases <https://github.com/FRRouting/frr/releases>`_. page. External
-contributors offer packages for many other platforms including \*BSD, Alpine,
-Gentoo, Docker, and others. There is currently no documentation on how to use
-those but we hope to add it soon.
+Up-to-date Debian & Redhat packages are available at
+https://deb.frrouting.org/ & https://rpm.frrouting.org/ respectively.
+
+Several distributions also provide packages for FRR. Check your
+distribution's repositories to find out if a suitable version is
+available.
+
 
 From Snapcraft
 --------------
@@ -29,12 +32,12 @@ universal Snap images, available at https://snapcraft.io/frr.
 From Source
 -----------
 
-Building FRR from source is the best way to ensure you have the latest features
-and bug fixes. Details for each supported platform, including dependency
-package listings, permissions, and other gotchas, are in the `developer's
-documentation
-<http://docs.frrouting.org/projects/dev-guide/en/latest/building.html>`_. This
-section provides a brief overview on the process.
+Building FRR from source is the best way to ensure you have the latest
+features and bug fixes. Details for each supported platform, including
+dependency package listings, permissions, and other gotchas, are in the
+`developer's documentation
+<http://docs.frrouting.org/projects/dev-guide/en/latest/building.html>`_.
+This section provides a brief overview on the process.
 
 
 Getting the Source

doc/user/introduction.rst

@@ -0,0 +1,13 @@
+.. _introduction:
+
+############
+Introduction
+############
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   installation
+   setup
+

doc/user/protocols.rst

@@ -0,0 +1,35 @@
+.. _protocols:
+
+#########
+Protocols
+#########
+
+.. toctree::
+   :maxdepth: 2
+
+   zebra
+   bfd
+   bgp
+   babeld
+   fabricd
+   ldpd
+   eigrpd
+   evpn
+   isisd
+   nhrpd
+   ospfd
+   ospf6d
+   pathd
+   pim
+   pimv6
+   pbr
+   ripd
+   ripngd
+   sharp
+   static
+   vnc
+   vrrp
+   bmp
+   watchfrr
+   mgmtd
+

doc/user/subdir.am

@@ -29,7 +29,7 @@ user_RSTFILES = \
 	doc/user/ospf6d.rst \
 	doc/user/ospfd.rst \
 	doc/user/ospf_fundamentals.rst \
-	doc/user/overview.rst \
+	doc/user/about.rst \
 	doc/user/packet-dumps.rst \
 	doc/user/pathd.rst \
 	doc/user/pim.rst \