From ee49365753e420eac8e5082d834a96834429e945 Mon Sep 17 00:00:00 2001
From: Varac <varac@varac.net>
Date: Mon, 16 Aug 2021 22:47:50 +0200
Subject: [PATCH] Split navigation into first steps, maintenance, reference

---
 docs/conf.py             |  3 +++
 docs/index.rst           | 27 +++++++++++++++++++++++----
 docs/maintenance.rst     |  4 ++--
 docs/troubleshooting.rst | 10 +++++-----
 4 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 41ef6396f..6866ac98c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -60,6 +60,9 @@ html_static_path = ['_static']
 # 'contents'
 master_doc = 'index'
 
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
+#
 # Suppress autosectionlabel extension warnings about duplicate labels, i.e.
 #
 #   docs/usage.rst:105: WARNING: duplicate label wordpress, other instance in docs/testing.rst
diff --git a/docs/index.rst b/docs/index.rst
index 5b447df14..ea1282f68 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,18 +22,37 @@ For more information, go to `the OpenAppStack website`_.
 
 .. _the OpenAppStack website: https://openappstack.net
 
+First steps
+-----------
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: First steps
 
    installation
    usage
    testing
+   advanced_installation
+
+Maintenance
+-----------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Maintenance
+
    maintenance
+   upgrading
    troubleshooting
-   advanced_installation
    security
-   upgrading
+
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   reference
    comparable_projects
    design
-   reference
diff --git a/docs/maintenance.rst b/docs/maintenance.rst
index 61a7a5233..ac8b107d7 100644
--- a/docs/maintenance.rst
+++ b/docs/maintenance.rst
@@ -1,5 +1,5 @@
-Maintaining an Openappstack cluster
-===================================
+Maintenance
+===========
 
 Logging
 -------
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index c9ded3b0f..330f2e5a2 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -66,13 +66,13 @@ Run all tests
 
    py.test -s --ansible-inventory=${CLUSTER_DIR}/inventory.yml --hosts='ansible://*'
 
-Test all applications 
+Test all applications
 '''''''''''''''''''''
 
 This will check for:
 
 * The applications return proper certificates
-* All helm releases are successfully installed 
+* All helm releases are successfully installed
 * All app pods are running and healthy (this test includes all optional
   applications)
 
@@ -262,7 +262,7 @@ In this example we fix a failed certificate request for
 *https://chat.oas.example.org*.  We will start by checking if ``cert-manager``
 is set up correctly.
 
-Is your cluster using the live ACME server? 
+Is your cluster using the live ACME server?
 
 .. code:: bash
 
@@ -278,7 +278,7 @@ Are all cert-manager pods in the `oas` namespace in the `READY` state ?
    $ kubectl -n cert-manager get pods
 
 Cert-manager uses a "custom resource" to keep track of your certificates, so you
-can also check the status of your certificates by running: 
+can also check the status of your certificates by running:
 
 This returns all the certificates for all applications on your system. The
 command includes example output of healthy certificates.
@@ -387,7 +387,7 @@ If all your ``kustomizations`` are in a ``Ready`` state, take a look at your
    cluster$ flux get helmreleases -A
 
 Often, you can resolve complications with ``kustomizations`` or ``helmreleases``
-by telling Flux to *reconcile* them: 
+by telling Flux to *reconcile* them:
 
 .. code:: bash
 
-- 
GitLab