more doc improvements (#1952)

Author: aantn

docs/conf.py

@@ -92,9 +92,11 @@
     "configuration/defining-playbooks/creating-notifications.html": "/master/playbook-reference/defining-playbooks/creating-notifications.html",
     "configuration/defining-playbooks/external-playbook-repositories.html": "/master/playbook-reference/defining-playbooks/external-playbook-repositories.html",
     "configuration/defining-playbooks/index.html": "/master/playbook-reference/defining-playbooks/index.html",
-    "configuration/defining-playbooks/playbook-advanced.html": "/master/playbook-reference/defining-playbooks/playbook-advanced.html",
-    "configuration/defining-playbooks/playbook-basics.html": "/master/playbook-reference/defining-playbooks/playbook-basics.html",
-    "configuration/defining-playbooks/trigger-action-binding.html": "/master/playbook-reference/defining-playbooks/trigger-action-binding.html",
+    "configuration/defining-playbooks/playbook-advanced.html": "/master/playbook-reference/index.html",
+    "playbook-reference/defining-playbooks/playbook-advanced.html": "/master/playbook-reference/index.html",
+    "configuration/defining-playbooks/playbook-basics.html": "/master/playbook-reference/index.html",
+    "configuration/defining-playbooks/trigger-action-binding.html": "/master/playbook-reference/index.html#matching-actions-to-triggers",
+    "playbook-reference/defining-playbooks/trigger-action-binding.html": "/master/playbook-reference/index.html#matching-actions-to-triggers",
     "configuration/additional-settings.html": "/master/setup-robusta/additional-settings.html",
     "developer-guide/writing-playbooks.html": "/master/playbook-reference/defining-playbooks/index.html",
     "user-guide/slack.html": "/master/configuration/sinks/slack.html",
@@ -108,7 +110,8 @@
     "configuration/configuring-sinks.html": "/master/notification-routing/configuring-sinks.html",
     "how-it-works/privacy-and-security.html": "/master/setup-robusta/privacy-and-security.html",
     "how-it-works/index.html": "/master/playbook-reference/what-are-playbooks.html",
-    "playbook-reference/examples.html": "/master/playbook-reference/prometheus-examples/index.html",
+    "playbook-reference/examples.html": "/master/playbook-reference/builtin-alert-enrichment.html",
+    "playbook-reference/prometheus-examples/index.html": "/master/playbook-reference/builtin-alert-enrichment.html",
     "tutorials/playbook-track-changes.html": "/master/playbook-reference/kubernetes-examples/kubernetes-change-notifications.html",
     "tutorials/playbook-job-failure.html": "/master/playbook-reference/kubernetes-examples/kubernetes-change-notifications.html",
     "tutorials/playbook-failed-liveness.html": "/master/playbook-reference/kubernetes-examples/kubernetes-change-notifications.html",
@@ -167,7 +170,7 @@
     "user-guide/embedded-prometheus.html": "/master/configuration/alertmanager-integration/embedded-prometheus.html#enabling-the-embedded-prometheus",
     "user-guide/node-selector.html": "/master/setup-robusta/node-selector.html",
     "user-guide/interactivity.html": "/master/setup-robusta/additional-settings.html#two-way-interactivity",
-    "user-guide/flow-control.html": "/master/playbook-reference/defining-playbooks/playbook-advanced.html#using-filters-to-restrict-triggers",
+    "user-guide/flow-control.html": "/master/playbook-reference/index.html#using-filters-to-restrict-triggers",
     "catalog/triggers/index.html": "/master/playbook-reference/triggers/index.html",
     "catalog/triggers/kubernetes.html": "/master/playbook-reference/triggers/kubernetes.html",
     "catalog/triggers/smart.html": "/master/playbook-reference/triggers/kubernetes.html",
@@ -189,7 +192,7 @@
     "catalog/sinks/webex.html": "/master/configuration/sinks/webex.html",
     "catalog/sinks/VictorOps.html": "/master/configuration/sinks/VictorOps.html",
     "catalog/sinks/file.html": "/master/configuration/sinks/file.html",
-    "user-guide/trigger-action-binding.html": "/master/playbook-reference/defining-playbooks/playbook-basics.html#understanding-actions",
+    "user-guide/trigger-action-binding.html": "/master/playbook-reference/index.html#understanding-actions",
     "advanced/privacy-and-security.html": "/master/setup-robusta/privacy-and-security.html",
     "advanced/robusta-ui-triggers.html": "/master/setup-robusta/installation/index.html",
     "developer-guide/actions/index.html": "/master/playbook-reference/actions/index.html",
@@ -209,7 +212,9 @@
     "configuration/alertmanager-integration/troubleshooting-alertmanager.html": "/master/configuration/exporting/send-alerts-api.html",
     "configuration/alertmanager-integration/grafana-alert-manager.html": "/master/configuration/alertmanager-integration/grafana-self-hosted.html",
     "configuration/alertmanager-integration/grafana-cloud-mimir.html": "/master/configuration/alertmanager-integration/grafana-cloud.html",
-    "playbook-reference/what-are-playbooks.html": "/master/playbook-reference/overview.html",
+    "playbook-reference/what-are-playbooks.html": "/master/playbook-reference/index.html",
+    "playbook-reference/overview.html": "/master/playbook-reference/index.html",
+    "playbook-reference/defining-playbooks/playbook-basics.html": "/master/playbook-reference/index.html",
     "how-it-works/alert-builtin-enrichment.html": "/master/playbook-reference/builtin-alert-enrichment.html",
     "setup-robusta/installation/extend-prometheus-installation.html": "/master/setup-robusta/installation/standalone-installation.html",
     "playbook-reference/defining-playbooks/index.html": "/master/playbook-reference/index.html",

docs/configuration/alertmanager-integration/alert-custom-prometheus.rst

@@ -8,11 +8,10 @@ Create Custom Prometheus Alerts
 You can define new alerts in two ways using Robusta:
 
 1. Prometheus Alerts - Using PromQL
-2. Robusta Playbooks - Using :ref:`customPlaybooks YAML <What are Playbooks?>`
+2. Robusta Playbooks - Using :ref:`customPlaybooks YAML <Playbook Basics>`
 
 These methods are not mutually exclusive. Robusta playbooks can respond to Prometheus alerts, or they can generate
-alerts themselves by listening directly to the Kubernetes APIServer. To better understand the trade-offs, refer to
-:ref:`Should I generate alerts with Robusta or with Prometheus? <robusta-or-prometheus-alerts>`
+alerts themselves by listening directly to the Kubernetes APIServer.
 
 In this tutorial, we use the first method to generate a custom Prometheus alert using PromQL. In the next tutorial,
 we define a custom Robusta playbook that enhances the alert and makes it better.
@@ -109,4 +108,4 @@ Next Steps
 
 Learn how to enrich Prometheus alerts with more context, so that you can respond faster:
 
-* :ref:`Prometheus Alert Enrichment`
+* :ref:`Alert Enrichment <builtin-alert-enrichment>`

docs/configuration/alertmanager-integration/grafana-self-hosted.rst

@@ -93,7 +93,7 @@ To enable Robusta to correlate your Grafana alerts with the specific Kubernetes
     This is only required for Kubernetes alerts. You can send any alert to the Robusta timeline, including non-Kubernetes alerts.
 
 Option 2: Inline Alert Enrichment and Routing
-===========================================
+==============================================
 
 Use Robusta to enrich alerts inline with extra context and route them to :doc:`other systems </configuration/sinks/index>` (Slack, Microsoft Teams, etc.). Learn more about :doc:`alert routing </notification-routing/index>`.
 

docs/configuration/holmesgpt/getting-started.rst

@@ -142,6 +142,8 @@ Instead of Robusta AI, you can use your own OpenAI, Azure, or AWS Bedrock accoun
                     name: holmes-secrets
                     key: awsSecretAccessKey
 
+.. _Reading the Robusta UI Token from a secret in HolmesGPT:
+
 Using Existing Secrets
 ----------------------
 

docs/configuration/resource-recommender.rst

@@ -1,13 +1,13 @@
 Cost Savings (KRR)
 ************************************************************
 
-Robustas `KRR <https://github.com/robusta-dev/krr>`_ is a CLI tool for optimizing resource allocation in Kubernetes clusters.
-It gathers pod usage data from Prometheus and recommends requests and limits for CPU and memory. This reduces costs and improves performance.
+`KRR <https://github.com/robusta-dev/krr>`_ is a CLI tool that optimizes resource allocation in Kubernetes clusters.
+It gathers pod usage data from Prometheus and recommends requests and limits for CPU and memory, reducing costs and improving performance.
 
-By optionally integrating KRR with Robusta you can:
+Robusta can run KRR scans on a :ref:`schedule <Scheduled>` using playbooks. Because KRR is so popular, it has dedicated documentation here. You can:
 
-1. Get weekly KRR scan reports in Slack via Robusta OSS (disabled by default, see below to configure)
-2. View KRR scans from all your clusters in the Robusta UI (enabled by default for UI users)
+1. Send weekly scan reports to Slack or other sinks via Robusta OSS (disabled by default, configure below)
+2. View scans from all your clusters in the Robusta UI (enabled by default for UI users)
 
 
 Sending Weekly KRR Scan Reports to Slack

docs/help.rst

@@ -1,5 +1,7 @@
 :hide-toc:
 
+.. _Getting Support:
+
 Getting Support
 ================
 
@@ -248,7 +250,7 @@ Holmes
 
         It's often because the ``Robusta UI Token`` is pulled from a secret, and Holmes cannot read it.
 
-        See :ref:`Reading the Robusta UI Token from a secret in HolmesGPT` to configure Holmes to read the ``token``
+        See :ref:`Using Existing Secrets <Reading the Robusta UI Token from a secret in HolmesGPT>` to configure Holmes to read the ``token``
 
 Phase 4: Integration Issues
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/how-it-works/coverage.rst

@@ -20,7 +20,7 @@ Prometheus Alerts
 
 .. warning::
 
-    You must :ref:`send your Prometheus alerts to Robusta by webhook <Integrating with Prometheus>` for these to work.
+    You must send your Prometheus alerts to Robusta by webhook for these to work. See :doc:`AlertManager Integration </configuration/alertmanager-integration/index>`.
 
 Other errors
 ----------------
@@ -39,8 +39,7 @@ Change Tracking
 By default all changes to Deployments, DaemonSets, and StatefulSets are sent to the Robusta UI for correlation
 with Prometheus alerts and other errors.
 
-These changes are not sent to other sinks (e.g. Slack) by default because they are spammy. :ref:`Routing Cookbook`
-explains how to selectively track changes you care about in Slack as well.
+These changes are not sent to other sinks (e.g. Slack) by default because they are spammy. See :doc:`Notification Routing </notification-routing/index>` to learn how to selectively track changes you care about in Slack as well.
 
 We also wrote a blog post `Why everyone should track Kubernetes changes and top four ways to do so <https://home.robusta.dev/blog/why-everyone-should-track-and-audit-kubernetes-changes-and-top-ways/>`_
 

docs/index.rst

@@ -144,10 +144,15 @@
    :hidden:
 
    playbook-reference/index
-   Builtin Alert Enrichment <playbook-reference/builtin-alert-enrichment>
-   Custom Alert Enrichment <playbook-reference/prometheus-examples/index>
-   Kubernetes Change Notifications <playbook-reference/kubernetes-examples/kubernetes-change-notifications>
+   Playbook Notifications <playbook-reference/defining-playbooks/creating-notifications>
+   Alert Enrichment <playbook-reference/builtin-alert-enrichment>
+   Automatic Remediation <playbook-reference/automatic-remediation-examples/index>
+   Change Tracking Playbooks <playbook-reference/kubernetes-examples/kubernetes-change-notifications>
+   Silencer Playbooks <playbook-reference/defining-playbooks/silencer-playbooks>
+   Log Based Alerting <playbook-reference/logs-triggers/index>
    Cost Savings - KRR <configuration/resource-recommender>
+   Triggers Reference <playbook-reference/triggers/index>
+   Actions Reference <playbook-reference/actions/index>
 
 .. toctree::
    :maxdepth: 4

docs/notification-routing/configuring-sinks.rst

@@ -9,7 +9,7 @@ A Simple Sink Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Sinks are defined in Robusta's Helm chart, using the ``sinksConfig`` value.
 
-For example, lets add a :ref:`Microsoft Teams Sink <MS Teams sink>`:
+For example, lets add a :ref:`Microsoft Teams Sink <MS Teams>`:
 
 .. code-block:: yaml
 

docs/notification-routing/index.rst

@@ -68,7 +68,7 @@ Popular Sinks
 
     .. grid-item-card:: PagerDuty
         :class-card: sd-bg-light sd-bg-text-light
-        :link: ../configuration/sinks/pagerduty
+        :link: ../configuration/sinks/PagerDuty
         :link-type: doc
 
     .. grid-item-card:: View All Sinks