Fix internal references

docs/conf.py

@@ -69,5 +69,6 @@ master_doc = 'index'
 #   docs/usage.rst:105: WARNING: duplicate label wordpress, other instance in docs/testing.rst
 #
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings
-suppress_warnings = ['autosectionlabel.*']
+# suppress_warnings = ['autosectionlabel.*']
 autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 5

docs/logging.rst

@@ -13,17 +13,47 @@ Central log aggregation
 
 We use `Promtail`_, `Loki`_ and `Grafana`_ for easy access of aggregated
 logs. The `Loki documentation`_ is a good starting point how this setup
-works, and the `Using Loki in Grafana`_ gets you started with querying
-your cluster logs with Grafana.
+works.
+There are two ways of viewing aggregated logs:
+
+* Via the Grafana web interface
+* Using the ``logcli`` command line tool
+
+
+Viewing logs in Grafana
+~~~~~~~~~~~~~~~~~~~~~~~
 
+The `Using Loki in Grafana`_ gets you started with querying
+your cluster logs with Grafana.
 You will find the Loki Grafana integration on your cluster at
 https://grafana.stackspin.example.org/explore together with some generic query
 examples.
 
+Please follow :ref:`logging:LogQL query examples` for more LogQL query examples.
+
+Query logs with logcli
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Please refer to `logcli`_ for installing ``logcli`` on your Laptop.
+The create a port-forwarding to your cluster using the ``kubectl`` tool:
+
+.. code:: bash
+
+   kubectl -n stackspin port-forward pod/loki-0 3100
+
+In another terminal you can now use ``logcli`` to query ``loki`` like this:
+
+.. code:: bash
+
+    logcli query '{app=~".+"}'
+
+Please follow :ref:`logging:LogQL query examples` for more LogQL query examples.
+
 LogQL query examples
 ~~~~~~~~~~~~~~~~~~~~
 
-Please also refer to the `LogQL documentation`_.
+Please also refer to the `LogQL documentation`_ and the
+`log queries documentation`_ .
 
 Query all aggregated logs (unfortunatly we can’t find a better way of
 doing this since LogQL always expects a stream label to get queried):
@@ -131,7 +161,9 @@ Show only warnings and errors from ``hydra``:
 .. _Grafana: https://grafana.com/
 .. _Loki documentation: https://grafana.com/docs/loki/latest/
 .. _Using Loki in Grafana: https://grafana.com/docs/grafana/latest/datasources/loki
+.. _logcli: https://grafana.com/docs/loki/latest/getting-started/logcli/
 .. _LogQL documentation: https://grafana.com/docs/loki/latest/logql
+.. _log queries documentation: https://grafana.com/docs/loki/latest/logql/log_queries/
 .. _Flux: https://fluxcd.io/
 .. _reach out to us: https://stackspin.net/contact.html
 .. _taints: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/

docs/troubleshooting.rst

@@ -15,12 +15,12 @@ described on our `contact page <https://stackspin.net/contact.html>`__. We
 want to be in communication with our users, and we want to help you if you run
 into problems.
 
-Known issues
-------------
+General known issues
+--------------------
 
 If you run into a problem, please check our `issue
 tracker <https://open.greenhost.net/groups/stackspin/-/issues>`__ to see if
-others have run into the same problem. We might have suggested a workaround or
+thers have run into the same problem. We might have suggested a workaround or
 temporary solution in one of our issues. If your problems is not described in an
 issue, please open a new one so we can solve the problems you encounter.
 
@@ -95,7 +95,7 @@ Tests a specific application
 Known Issues
 ''''''''''''
 
-The Default ssh backend for testinfra tests is ``paramiko``, which doesn't work
+The default ssh backend for testinfra tests is ``paramiko``, which doesn't work
 out of the box. It fails to connect to the host because the ``ed25519`` hostkey
 was not verified. Therefore we need to force plain ssh:// with either
 ``connection=ssh`` or ``--hosts=ssh://…``
@@ -140,8 +140,8 @@ You can also only run a Taiko test for a specific application, i.e.:
 Advanced usage
 ~~~~~~~~~~~~~~
 
-Testinfra tests
-'''''''''''''''
+Advanced Testinfra tests
+''''''''''''''''''''''''
 
 Specify host manually:
 
@@ -190,8 +190,8 @@ then:
 
     gitlab-runner exec docker --env CI_REGISTRY_IMAGE="$CI_REGISTRY_IMAGE" --env SSH_PRIVATE_KEY="$SSH_PRIVATE_KEY" --env COSMOS_API_TOKEN="$COSMOS_API_TOKEN" bootstrap
 
-Taiko tests
-'''''''''''
+Advanced Taiko tests
+''''''''''''''''''''
 
 If you want to use Taiko without invoking the stackspin CLI, go to the
 ``test/taiko`` directory and run: