docs tweaks (#1946)

aantn · web-flow · commit 2ace01325e44 · 2025-10-28T21:09:27.000Z
diff --git a/docs/configuration/sinks/index.rst b/docs/configuration/sinks/index.rst
@@ -2,41 +2,11 @@
 
 :hide-toc:
 
-Sink Reference
+All Sinks
 ==================
 
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-
-   slack
-   ms-teams
-   RobustaUI
-   mail
-   telegram
-   discord
-   DataDog
-   mattermost
-   Opsgenie
-   PagerDuty
-   VictorOps
-   YandexMessenger
-   jira
-   webhook
-   file
-   webex
-   kafka
-   rocketchat
-   google_chat
-   pushover
-   ServiceNow
-   zulip
-   sinks-development
-
-
-Robusta can report issues and events in your Kubernetes cluster to various destinations, known as sinks.
-
-By default, Robusta sends all notifications to all sinks.
+
+Robusta can send notifications to various destinations, known as sinks.
 
 **Related Topics:**
 
diff --git a/docs/configuration/sinks/sinks-development.rst b/docs/configuration/sinks/sinks-development.rst
@@ -6,7 +6,7 @@ If Robusta doesn't support the sink you need, consider implementing your own.
 What Are Robusta Sinks?
 --------------------------
 
-:ref:`Sinks <Sinks Reference>` are the destinations to which Robusta sends data. For example, when sending Robusta messages
+:ref:`Sinks <sinks-reference>` are the destinations to which Robusta sends data. For example, when sending Robusta messages
 to Slack, Robusta uses a Slack sink.
 
 Internally, Robusta generates
diff --git a/docs/index.rst b/docs/index.rst
@@ -49,17 +49,53 @@
 
 .. toctree::
    :maxdepth: 4
-   :caption: 🔔 Notifications & Routing
+   :caption: 🔔 Notification Sinks
+   :hidden:
+
+   Overview <notification-routing/configuring-sinks>
+   All Sinks <configuration/sinks/index>
+   configuration/sinks/slack
+   configuration/sinks/ms-teams
+   configuration/sinks/RobustaUI
+   configuration/sinks/mail
+   configuration/sinks/telegram
+   configuration/sinks/discord
+   configuration/sinks/DataDog
+   configuration/sinks/mattermost
+   configuration/sinks/Opsgenie
+   configuration/sinks/PagerDuty
+   configuration/sinks/VictorOps
+   configuration/sinks/YandexMessenger
+   configuration/sinks/jira
+   configuration/sinks/webhook
+   configuration/sinks/file
+   configuration/sinks/webex
+   configuration/sinks/kafka
+   configuration/sinks/rocketchat
+   configuration/sinks/google_chat
+   configuration/sinks/pushover
+   configuration/sinks/ServiceNow
+   configuration/sinks/zulip
+   configuration/sinks/sinks-development
+
+.. toctree::
+   :maxdepth: 4
+   :caption: 🔀 Alert Routing
    :hidden:
 
    Overview <notification-routing/index>
-   notification-routing/configuring-sinks
-   📧 Sink Reference <configuration/sinks/index>
    Routing (Scopes) <notification-routing/routing-with-scopes>
    Grouping (Slack Threads) <notification-routing/notification-grouping>
    notification-routing/routing-by-time
+   notification-routing/routing-by-namespace
+   notification-routing/routing-by-type
+   notification-routing/implementing-monitoring-shifts
+   notification-routing/routing-to-multiple-slack-channels
+   notification-routing/routing-exclusion
+   notification-routing/routing-by-severity
+   notification-routing/excluding-resolved
+   notification-routing/disable-oomkill-notifications
    notification-routing/routing-silencing
-   notification-routing/notification-routing-examples
 
 .. toctree::
    :maxdepth: 4
diff --git a/docs/notification-routing/configuring-sinks.rst b/docs/notification-routing/configuring-sinks.rst
@@ -5,8 +5,6 @@ Defining Sinks
 
 Robusta can send notifications to various destinations, called sinks.
 
-For a list of all sinks, refer to :ref:`Sinks Reference`.
-
 A Simple Sink Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Sinks are defined in Robusta's Helm chart, using the ``sinksConfig`` value.
@@ -86,7 +84,7 @@ Description of each option:
 |                  | explicitly named this sink (if scope is set, it will    |                                                          |                                               |
 |                  | still filter those notifications)                       |                                                          |                                               |
 +------------------+---------------------------------------------------------+----------------------------------------------------------+-----------------------------------------------+
-| *sink specific*  | Parameters specific to the sink type, like api_key for  | -                                                        | :ref:`sink-specific docs <Sinks Reference>`   |
+| *sink specific*  | Parameters specific to the sink type, like api_key for  | -                                                        | :ref:`sink-specific docs <sinks-reference>`   |
 | *parameters*     | Slack and webhook_url for MSTeams                       |                                                          |                                               |
 +------------------+---------------------------------------------------------+----------------------------------------------------------+-----------------------------------------------+
 
@@ -109,5 +107,5 @@ In order to enable that, add the below to ``globalConfig`` in your ``generated_v
 Learn More
 ^^^^^^^^^^^^
 
-* 🔔 :ref:`All Sinks <Sinks Reference>`
+* 🔔 :ref:`All Sinks <sinks-reference>`
 * ↳ :ref:`Routing (scopes) <sink-scope-matching>`
diff --git a/docs/notification-routing/routing-by-namespace.rst b/docs/notification-routing/routing-by-namespace.rst
@@ -6,7 +6,7 @@ You can route alerts based on the Kubernetes namespace they relate to. This is i
 Prerequisites
 ----------------
 
-* At least one existing :ref:`sink <Sinks Reference>`, such as Slack, Microsoft Teams, Discord, etc.
+* At least one existing :ref:`sink <sinks-reference>`, such as Slack, Microsoft Teams, Discord, etc.
 
 Setting Up Routing
 ----------------------
diff --git a/docs/notification-routing/routing-by-type.rst b/docs/notification-routing/routing-by-type.rst
@@ -1,7 +1,7 @@
 Route By Alert Name
 =============================
 
-By default, Robusta notifications are sent to all :ref:`sinks <Sinks Reference>`.
+By default, Robusta notifications are sent to all :ref:`sinks <sinks-reference>`.
 
 In this guide, you'll learn to route alerts by their name:
 
@@ -11,7 +11,7 @@ In this guide, you'll learn to route alerts by their name:
 Prerequisites
 ----------------
 
-All least one existing :ref:`sink <Sinks Reference>` must be configured. Below, we'll assume it's a Slack sink.
+All least one existing :ref:`sink <sinks-reference>` must be configured. Below, we'll assume it's a Slack sink.
 
 Setting Up Routing
 ----------------------
diff --git a/docs/playbook-reference/kubernetes-examples/playbook-failed-liveness.rst b/docs/playbook-reference/kubernetes-examples/playbook-failed-liveness.rst
@@ -1,7 +1,7 @@
 Track Failed Liveness Probes
 ##############################
 
-Lets track failed Liveness Probes and notify the user. Notifications will be sent to configured :ref:`Sinks <Sinks Reference>`
+Lets track failed Liveness Probes and notify the user. Notifications will be sent to configured :ref:`Sinks <sinks-reference>`
 like Slack or MSTeams. It is also possible to :ref:`route notifications to specific sinks<Routing Alerts to Specific Sinks>`.
 
 Define a Playbook to Track Liveness Probes
diff --git a/docs/playbook-reference/kubernetes-examples/playbook-job-failure.rst b/docs/playbook-reference/kubernetes-examples/playbook-job-failure.rst
@@ -1,7 +1,7 @@
 Track Failed Kubernetes Jobs
 ##############################
 
-Notify about failed Kubernetes Jobs in Slack, MSTeams or other :ref:`Sinks <Sinks Reference>`.
+Notify about failed Kubernetes Jobs in Slack, MSTeams or other :ref:`Sinks <sinks-reference>`.
 
 .. image:: /images/failingjobs.png
     :alt: Failing Kubernetes jobs notification on Slack
diff --git a/docs/playbook-reference/kubernetes-examples/playbook-track-changes.rst b/docs/playbook-reference/kubernetes-examples/playbook-track-changes.rst
@@ -74,7 +74,7 @@ Run the following YAML files to simulate a deployment image change
   kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/deployment_image_change/before_image_change.yaml
   kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/deployment_image_change/after_image_change.yaml
 
-A Robusta notification will arrive in your configured :ref:`sinks <Sinks Reference>`, showing exactly what changed in the deployment.
+A Robusta notification will arrive in your configured :ref:`sinks <sinks-reference>`, showing exactly what changed in the deployment.
 
 **Sample Alert**:
 
@@ -133,7 +133,7 @@ Run the following commands to simulate ingress changes:
   kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/ingress_port_path_change/before_port_path_change.yaml
   kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/ingress_port_path_change/after_port_path_change.yaml
 
-A Robusta notification will arrive in your configured :ref:`sinks <Sinks Reference>`, showing exactly what changed in the ingress.
+A Robusta notification will arrive in your configured :ref:`sinks <sinks-reference>`, showing exactly what changed in the ingress.
 
 **Sample Alert**:
 
diff --git a/docs/playbook-reference/kubernetes-examples/playbook-track-secrets.rst b/docs/playbook-reference/kubernetes-examples/playbook-track-secrets.rst
@@ -114,7 +114,7 @@ Then perform a :ref:`Helm Upgrade <Simple Upgrade>`.
 
        kubectl delete secret test-secret
 
-A Robusta notification will arrive in your configured :ref:`sinks <Sinks Reference>`, indicating that the Secret was created, modified, or deleted.
+A Robusta notification will arrive in your configured :ref:`sinks <sinks-reference>`, indicating that the Secret was created, modified, or deleted.
 
 
 Cleanup
diff --git a/docs/playbook-reference/what-are-playbooks.rst b/docs/playbook-reference/what-are-playbooks.rst
@@ -12,7 +12,7 @@ Conceptually, Robusta does three things:
 
 1. **Listens passively to various sources:** Robusta monitors Kubernetes events, Prometheus alerts, and other sources to stay informed about your cluster's current state.
 2. **Actively collects observability data:** When noteworthy events occur, Robusta actively gathers and correlates information such as logs, graphs, and thread dumps. All according to the playbooks defined in Robusta.
-3. **Sends notifications:** Based on your preferences, Robusta notifies in :ref:`sinks <Sinks Reference>` like Slack, MSTeams, and PagerDuty
+3. **Sends notifications:** Based on your preferences, Robusta notifies in :ref:`sinks <sinks-reference>` like Slack, MSTeams, and PagerDuty
 
 To get a feel for playbooks, let's explore two examples:
 
diff --git a/docs/setup-robusta/installation/_see_robusta_in_action.rst b/docs/setup-robusta/installation/_see_robusta_in_action.rst
@@ -17,7 +17,7 @@ Verify the pod is crashing:
    NAME                            READY   STATUS             RESTARTS   AGE
    crashpod-64d8fbfd-s2dvn         0/1     CrashLoopBackOff   1          7s
 
-Once the pod restarts twice, you'll get notified in your configured :ref:`sink <Sinks Reference>`.
+Once the pod restarts twice, you'll get notified in your configured :ref:`sink <sinks-reference>`.
 
 .. admonition:: Example Slack Message
 
diff --git a/docs/setup-robusta/proxies.rst b/docs/setup-robusta/proxies.rst
@@ -4,7 +4,7 @@ Deploying Behind Proxies
 Robusta requires internet access in the following cases:
 
 * Robusta SaaS is enabled
-* Robusta is configured to send notifications to services such as Slack (via :ref:`sinks <Sinks Reference>`)
+* Robusta is configured to send notifications to services such as Slack (via :ref:`sinks <sinks-reference>`)
 
 If your Kubernetes cluster is behind an HTTP proxy or firewall, follow the instructions below to ensure Robusta and HolmesGPT has the necessary access.
 
