Merge pull request #16297 from qlyoung/doc-toc-sections

doc: improve table-of-contents organization

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 \