toc: on the way to a better structured toc

9 files changed, 59 insertions, 66 deletions

diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst
index dcd77cdd..9c142865 100644
--- a/docs/image-mgmt.rst
+++ b/docs/image-mgmt.rst
@@ -1,7 +1,8 @@
 .. _image-mgmt:
 
-System Image Management
-=======================
+################
+Image Management
+################
 
 The VyOS image-based installation is implemented by creating a directory for
 each image on the storage device selected during the install process.
@@ -45,14 +46,6 @@ command in operational mode.
      2: 1.2.0-rolling+201810021217
      3: 1.2.0-rolling+201809280337
      4: 1.2.0-rolling+201809252218
-     5: 1.2.0-rolling+201809192034
-     6: 1.2.0-rolling+201809191744
-     7: 1.2.0-rolling+201809150337
-     8: 1.2.0-rolling+201809141130
-     9: 1.2.0-rolling+201809140949
-    10: 1.2.0-rolling+201809131722
-
-  vyos@vyos:~$
 
 Images no longer needed can be removed using the :code:`delete system image`
 command.
@@ -60,12 +53,12 @@ command.
 .. _update_vyos:
 
 Update VyOS
------------
+===========
 
-Finally, new system images can be added using the :code:`add system image` command.
-The add image command will extract the image from the release ISO (either on
-the local filesystem or remotely if a URL is provided). The image install
-process will prompt you to use the current system configuration and SSH
+Finally, new system images can be added using the :code:`add system image`
+command. The add image command will extract the image from the release ISO
+(either on the local filesystem or remotely if a URL is provided). The image
+install process will prompt you to use the current system configuration and SSH
 security keys, allowing for the new image to boot using the current
 configuration.
 
diff --git a/docs/index.rst b/docs/index.rst
index 19bec74e..e446ec27 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,17 +27,27 @@ Basics
 
    configuration-overview
    interfaces/index
+   system/index
+   image-mgmt
+
+########
+Advanced
+########
+
+.. _introduction:
+.. toctree::
+   :maxdepth: 2
+
    routing/index
    firewall
    nat
    vpn/index
    qos
    services/index
-   system/index
+
    high-availability
    clustering
    load-balancing
-   image-mgmt
    commandscripting
    troubleshooting
 
diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst
index 9aebf7df..93f9579c 100644
--- a/docs/interfaces/index.rst
+++ b/docs/interfaces/index.rst
@@ -1,7 +1,8 @@
 .. _network-interfaces:
 
+##################
 Network Interfaces
-==================
+##################
 
 Configured interfaces on a VyOS system can be displayed using the
 ``show interfaces`` command.
diff --git a/docs/routing/arp.rst b/docs/routing/arp.rst
index 11371d49..a1a8c430 100644
--- a/docs/routing/arp.rst
+++ b/docs/routing/arp.rst
@@ -1,7 +1,8 @@
 .. _routing-arp:
 
+###
 ARP
----
+###
 
 :abbr:`ARP (Address Resolution Protocol)` is a communication protocol used for
 discovering the link layer address, such as a MAC address, associated with a
@@ -15,13 +16,16 @@ provided by the Neighbor Discovery Protocol (NDP).
 To manipulate or display ARP_ table entries, the following commands are
 implemented.
 
-Add static ARP entry
-^^^^^^^^^^^^^^^^^^^^
+Configure
+=========
 
-.. cfcmd:: set protocols static arp 10.1.1.100 hwaddr 08:00:27:de:23:aa
+.. cfcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa
 
-Display ARP entries
-^^^^^^^^^^^^^^^^^^^
+This will configure a static ARP entry always resolving `192.0.2.100` to
+`00:53:27:de:23:aa`
+
+Operation
+=========
 
 .. opcmd:: show protocols static arp
 
diff --git a/docs/routing/index.rst b/docs/routing/index.rst
index 1a1db43f..b49120f7 100644
--- a/docs/routing/index.rst
+++ b/docs/routing/index.rst
@@ -1,11 +1,8 @@
 .. _routing:
 
+#######
 Routing
-=======
-
-VyOS is a "router first" network operating system. It supports static routing,
-policy routing, and dynamic routing using standard protocols (RIP, OSPF, and
-BGP).
+#######
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/routing/static.rst b/docs/routing/static.rst
index b2c7833a..3c042844 100644
--- a/docs/routing/static.rst
+++ b/docs/routing/static.rst
@@ -1,7 +1,8 @@
 .. _routing-static:
 
-Static
-------
+#############
+Static Routes
+#############
 
 Static routes are manually configured network routes.
 
diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst
index 055a2d5c..54b40f8f 100644
--- a/docs/vpn/index.rst
+++ b/docs/vpn/index.rst
@@ -5,10 +5,8 @@
 VPN
 ===
 
-This chapter describes the available VPN services provided by VyOS.
-
 .. toctree::
-   :hidden:
+   :maxdepth: 2
 
    openvpn
    l2tp
diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst
index 63949184..1a9ee9cf 100644
--- a/docs/vpn/openvpn.rst
+++ b/docs/vpn/openvpn.rst
@@ -1,7 +1,8 @@
 .. _openvpn:
 
+#######
 OpenVPN
--------
+#######
 
 Traditionally hardware routers implement IPsec exclusively due to relative
 ease of implementing it in hardware and insufficient CPU power for doing
@@ -31,8 +32,8 @@ In the VyOS CLI, a key point often overlooked is that rather than being
 configured using the `set vpn` stanza, OpenVPN is configured as a network
 interface using `set interfaces openvpn`.
 
-OpenVPN Site-To-Site
-^^^^^^^^^^^^^^^^^^^^
+Site-To-Site
+============
 
 While many are aware of OpenVPN as a Client VPN solution, it is often
 overlooked as a site-to-site VPN solution due to lack of support for this mode
@@ -178,8 +179,8 @@ to each tunnel. Another option is to dedicate a port number to each tunnel
 OpenVPN status can be verified using the `show openvpn` operational commands.
 See the built-in help for a complete list of options.
 
-OpenVPN Server
-^^^^^^^^^^^^^^
+Server
+======
 
 Multi-client server is the most popular OpenVPN mode on routers. It always uses
 x.509 authentication and therefore requires a PKI setup. This guide assumes you
@@ -255,10 +256,10 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves:
 
 
 Client Authentication
-*********************
+---------------------
 
-OpenLDAP
-========
+LDAP
+****
 
 Enterprise installations usually ship a kind of directory service which is used
 to have a single password store for all employees. VyOS and OpenVPN support using
@@ -297,7 +298,7 @@ The required config file may look like:
   </Authorization>
 
 Active Directory
-================
+****************
 
 Despite the fact that AD is a superset of LDAP
 
@@ -382,8 +383,8 @@ A complete LDAP auth OpenVPN configuration could look like the following example
        }
    }
 
-OpenVPN Client
-^^^^^^^^^^^^^^
+Client
+======
 
 VyOS can not only act as an OpenVPN site-to-site or Server for multiple clients.
 You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client
@@ -394,9 +395,8 @@ and another VyOS router acting as OpenVPN client. The Server also pushes a
 static client IP address to the OpenVPN client. Remember, clients are identified
 using their CN attribute in the SSL certificate.
 
-
 Server
-******
+------
 
 .. code-block:: sh
 
@@ -420,7 +420,7 @@ Server
   set interfaces openvpn vtun10 use-lzo-compression
 
 Client
-******
+------
 
 .. code-block:: sh
 
@@ -437,7 +437,7 @@ Client
   set interfaces openvpn vtun10 use-lzo-compression
 
 Options
-^^^^^^^
+=======
 
 We do not have CLI nodes for every single OpenVPN options. If an option is
 missing, a feature request should be opened at https://phabricator.vyos.net so
@@ -446,20 +446,16 @@ all users can benefit from it.
 If you are a hacker or want to try on your own we support passing raw OpenVPN
 options to OpenVPN.
 
-.. code-block:: sh
-
-  set interfaces openvpn vtun10 openvpn-option 'persistent-key'
+.. cfcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key'
 
 Will add ``persistent-key`` at the end of the generated OpenVPN configuration.
 Please use this only as last resort - things might break and OpenVPN won't start
 if you pass invalid options/syntax.
 
-Sometimes option lines in the generated OpenVPN configurarion require quotes.
-This is done through a hack on our config generator. You can pass Quotes using
-the ``&quot;`` statement.
-
-.. code-block:: sh
-
-  set interfaces openvpn vtun10 openvpn-option 'push &quot;keepalive 1 10&quot;'
+.. cfcmd:: set interfaces openvpn vtun10 openvpn-option 'push &quot;keepalive 1 10&quot;'
 
 Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file.
+
+.. note:: Sometimes option lines in the generated OpenVPN configurarion require
+   quotes. This is done through a hack on our config generator. You can pass
+   quotes using the ``&quot;`` statement.
diff --git a/docs/vpn/references.rst b/docs/vpn/references.rst
deleted file mode 100644
index be3d5921..00000000
--- a/docs/vpn/references.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-.. _`Google Public DNS`: https://developers.google.com/speed/public-dns
-.. _Quad9: https://quad9.net
-.. _CloudFlare: https://blog.cloudflare.com/announcing-1111
-.. _RADIUS: https://en.wikipedia.org/wiki/RADIUS
-.. _FreeRADIUS: https://freeradius.org
-.. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server
-.. _PPTP: https://en.wikipedia.org/wiki/Point-to-Point_Tunneling_Protocol