toc: build proper doc in html and pdf

6 files changed, 97 insertions, 72 deletions

diff --git a/docs/about.rst b/docs/about.rst
new file mode 100644
index 00000000..4af91890
--- /dev/null
+++ b/docs/about.rst
@@ -0,0 +1,29 @@
+.. _about:
+
+#####
+About
+#####
+
+VyOS is an open source network operating system based on Debian GNU/Linux.
+
+VyOS provides a free routing platform that competes directly with other
+commercially available solutions from well known network providers. Because
+VyOS is run on standard amd64, i586 and ARM systems, it is able to be used
+as a router and firewall platform for cloud deployments.
+
+We use multiple live versions of our manual hosted thankfully by
+https://readthedocs.org. We will provide one version of the manual for every
+VyOS major version starting with VyOS 1.2 which will receive Long-term support
+(LTS).
+
+The manual version is selected/specified by it's Git branch name. You can
+switch between versions of the documentation by selecting the appropriate
+branch on the bottom left corner.
+
+VyOS CLI syntax may change between major (and sometimes minor) versions. Please
+always refer to the documentation matching your current, running installation.
+If a change in the CLI is required, VyOS will ship a so called migration script
+which will take care of adjusting the synatax. No action needs to be taken by
+you.
+
+
diff --git a/docs/cli.rst b/docs/cli.rst
index c1306c82..10d8c1ec 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -1,27 +1,29 @@
 .. _cli:
 
-Command-Line Interface
-======================
+###
+CLI
+###
 
-The VyOS CLI comprises an :ref:`commandtree_operationmode` and a  :ref:`commandtree_configmode`.
+The VyOS :abbr:`CLI (Command-Line Interface)` comprises an
+:ref:`commandtree_operationmode` and a :ref:`commandtree_configmode`.
 
 Operational mode allows for commands to perform operational system tasks and
 view system and service status, while configuration mode allows for the
-modification of system configuration. The :ref:`command tree page<commandtree>` lists available commands and their functions.
+modification of system configuration. The :ref:`command tree page<commandtree>`
+lists available commands and their functions.
 
-The CLI provides a built-in help system. In the CLI the **[?]** key may be used
-to display available commands. The **[tab]** key can be used to auto-complete
+The CLI provides a built-in help system. In the CLI the ``?`` key may be used
+to display available commands. The ``TAB`` key can be used to auto-complete
 commands and will present the help system upon a conflict or unknown value.
 
-For example typing `sh` followed by the **[tab]** key will complete to `show`.
-Pressing **[tab]** a second time will display the possible sub-commands of the
-`show` command.
+For example typing ``sh`` followed by the ``TAB`` key will complete to
+``show``. Pressing ``TAB`` a second time will display the possible
+sub-commands of the ``show`` command.
 
 .. code-block:: sh
 
   vyos@vyos:~$ s[tab]
   set   show
-  vyos@vyos:~$
 
 Example showing possible show commands:
 
@@ -50,24 +52,24 @@ Example showing possible show commands:
     host          Show host information
     incoming      Show ethernet input-policy information
   : q
-  vyos@vyos:~$
 
-You can scroll up with the keys [Shift]+[PageUp] and sroll down with [Shift]+[PageDown].
+You can scroll up with the keys ``[Shift]+[PageUp]`` and scroll down with
+``[Shift]+[PageDown]``.
 
 When the output of a command results in more lines than can be displayed on the
-terminal screen the output is paginated as indicated by a : prompt.
+terminal screen the output is paginated as indicated by a ``:`` prompt.
 
 When viewing in page mode the following commands are available:
- * **[q]** key can be used to cancel output
- * **[space]** will scroll down one page
- * **[b]** will scroll back one page
- * **[return]** will scroll down one line
- * **[up-arrow]** and **[down-arrow]** will scroll up or down one line at a
+ * ``q`` key can be used to cancel output
+ * ``space`` will scroll down one page
+ * ``b`` will scroll back one page
+ * ``return`` will scroll down one line
+ * ``up-arrow`` and ``down-arrow`` will scroll up or down one line at a
    time respectively
- * **[left-arrow]** and **[right-arrow]** can be used to scroll left or right
+ * ``left-arrow`` and ``right-arrow`` can be used to scroll left or right
    in the event that the output has lines which exceed the terminal size.
 
-To enter configuration mode use the `configure` command:
+To enter configuration mode use the ``configure`` command:
 
 .. code-block:: sh
 
@@ -75,7 +77,8 @@ To enter configuration mode use the `configure` command:
   [edit]
   vyos@vyos:~#
 
-.. note:: Prompt changes from `$` to `#`. To exit configuration mode, type `exit`.
+.. note:: Prompt changes from ``$`` to ``#``. To exit configuration mode,
+   type ``exit``.
 
 .. code-block:: sh
 
diff --git a/docs/history.rst b/docs/history.rst
index a596cc79..b1393520 100644
--- a/docs/history.rst
+++ b/docs/history.rst
@@ -1,7 +1,8 @@
 .. _history:
 
+#######
 History
-=======
+#######
 
 VyOS is a Linux-based network operating system that provides software-based
 network routing, firewall, and VPN functionality.
@@ -18,9 +19,8 @@ syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the
 `XORP project <http://www.xorp.org/>`_, which was the original routing engine
 for Vyatta.
 
-In the 4.0 release of Vyatta, the routing engine was changed to Quagga.
-
-As of version 1.2, VyOS now uses `FRRouting <https://frrouting.org/>`_ as the
+In the 4.0 release of Vyatta, the routing engine was changed to Quagga. As of
+VyOS version 1.2, VyOS now uses `FRRouting <https://frrouting.org/>`_ as the
 routing engine.
 
 How is VyOS different from any other router distributions and platform?
diff --git a/docs/index.rst b/docs/index.rst
index 5f18c011..742b8eec 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,41 +3,28 @@
 VyOS User Guide
 ===============
 
-VyOS is an open source network operating system based on Debian GNU/Linux.
-
-VyOS provides a free routing platform that competes directly with other
-commercially available solutions from well known network providers. Because
-VyOS is run on standard amd64, i586 and ARM systems, it is able to be used
-as a router and firewall platform for cloud deployments.
-
-#####
-About
-#####
-
-We use multiple live versions of our manual hosted thankfully by
-https://readthedocs.org. We will provide one version of the manual for every
-VyOS major version starting with VyOS 1.2 which will receive Long-term support
-(LTS).
-
-The manual version is selected/specified by it's Git branch name. You can
-switch between versions of the documentation by selecting the appropriate
-branch on the bottom left corner.
-
-VyOS CLI syntax may change between major (and sometimes minor) versions. Please
-always refer to the documentation matching your current, running installation.
-If a change in the CLI is required, VyOS will ship a so called migration script
-which will take care of adjusting the synatax. No action needs to be taken by
-you.
+############
+Introduction
+############
 
 .. _introduction:
 .. toctree::
-   :caption: Introduction
    :maxdepth: 2
 
+   about
    history
    install
    cli
    quick-start
+
+######
+Basics
+######
+
+.. _introduction:
+.. toctree::
+   :maxdepth: 2
+
    configuration-overview
    interfaces/index
    routing/index
@@ -52,12 +39,13 @@ you.
    load-balancing
    image-mgmt
    commandscripting
-.. modules
 
+########
+Appendix
+########
 
 .. _appendix:
 .. toctree::
-   :caption: Appendix
    :maxdepth: 2
 
    appendix/releasenotes
@@ -68,10 +56,12 @@ you.
    appendix/vyos-on-baremetal
    appendix/migrate-from-vyatta
 
+############
+Contributing
+############
 
 .. _contributing:
 .. toctree::
-   :caption: Contributing
    :maxdepth: 2
 
    contributing/build-vyos
@@ -79,6 +69,7 @@ you.
    contributing/development
    contributing/documentation
 
+
 ################
 Copyright Notice
 ################
diff --git a/docs/install.rst b/docs/install.rst
index 8a7b60be..92b13c64 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -1,20 +1,21 @@
 .. _installation:
 
+############
 Installation
-============
+############
 
 Requirements
-------------
+============
 
 The recommended system requirements are 512 MiB RAM and 2 GiB storage. Depending
 on your use you might need additional RAM and CPU resources e.g. when having
 multiple BGP full tables in your system.
 
 Getting the software
----------------------
+====================
 
 Registered subscribers
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 Registered subscribers can log into https://support.vyos.io/ to have access to
 a variety of different downloads via the "Downloads" link. These downloads
@@ -25,15 +26,14 @@ ISOs.
 .. figure:: /_static/images/vyos-downloads.png
 
 Building from source
-^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 Non-subscribers can get the LTS release by building it from source. Instruction
-can be found here: :ref:`build`
-
-https://github.com/vyos/vyos-build
+can be found here: :ref:`build` and the source repository is available
+for everyone at https://github.com/vyos/vyos-build.
 
-Rolling releases
-^^^^^^^^^^^^^^^^
+Rolling Release
+---------------
 
 Non-subscribers and subscribers can download bleeding-edge VyOS rolling images
 from: https://downloads.vyos.io/
@@ -43,14 +43,15 @@ current branch:
 https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso
 
 
-Preparing software verification
--------------------------------
+Software verification
+=====================
 
 This subsection and the following one applies to downloaded LTS images, for
 other versions please jump to :ref:`Install`.
 
 LTS images are signed by VyOS lead package-maintainer private key. With the
 official public key, the authenticity of the package can be verified.
+:abbr:`GPG (GNU Privacy Guard)` is used for verification.
 
 First, install GPG or another OpenPGP implementation. On most GNU+Linux
 distributions it is installed by default as package managers use it to verify
@@ -141,8 +142,8 @@ The import can be verified with:
 
 .. _gpg-verification:
 
-GPG verification
-----------------
+GPG
+---
 
 With the public key imported, the signature for the desired image needs to be
 downloaded.
@@ -164,7 +165,7 @@ Finally, verify the authencity of the downloaded image:
 .. _Install:
 
 Install
--------
+=======
 
 VyOS ISO is a Live CD and will boot to a functional VyOS image.
 
@@ -324,7 +325,7 @@ Configure a TFTP server so that it serves the following:
 * The initial ramdisk of the VyOS ISO you want to deploy. That is the
   ``initrd.img`` file inside the ``/live`` directory of the extracted contents
   from the ISO file. Do not use an empty (0 bytes) initrd.img file you might
-  find, the correct file may have a longer name. 
+  find, the correct file may have a longer name.
 * A directory named pxelinux.cfg which must contain the configuration file:
   We will use the configuration_ file shown below, which we named default_
 
diff --git a/docs/quick-start.rst b/docs/quick-start.rst
index 2aa3cbbb..9021dea9 100644
--- a/docs/quick-start.rst
+++ b/docs/quick-start.rst
@@ -1,7 +1,8 @@
 .. _quick-start:
 
-Quick Start Guide
-=================
+###########
+Quick Start
+###########
 
 Below is a very basic configuration example that will provide a NAT gateway
 for a device with two interfaces.