docs tweaks

[aantn]

make it easier to find and read docs on sinks and alert routing

[coderabbitai]

Walkthrough

The PR updates documentation cross-references and reorganizes the sinks configuration page structure, renaming the "Sinks Reference" anchor to "sinks-reference" and updating all related links across multiple documentation files.

Changes

Cohort / File(s)	Change Summary
Sink Configuration docs/configuration/sinks/index.rst, docs/configuration/sinks/sinks-development.rst	Updated heading from "Sink Reference" to "All Sinks", removed toctree with explicit sink listing, simplified intro paragraph, and changed sink reference link anchor from "Sinks Reference" to "sinks-reference"
Documentation Index docs/index.rst	Reorganized notification-related sections: replaced "Notifications & Routing" caption with "Notification Sinks", added new "All Sinks" toctree, introduced new "Alert Routing" nested toctree with expanded routing topics, removed old notification-routing pages
Notification Routing docs/notification-routing/configuring-sinks.rst, docs/notification-routing/routing-by-namespace.rst, docs/notification-routing/routing-by-type.rst	Updated sink reference cross-references from "Sinks Reference" to "sinks-reference" anchor throughout prerequisites and introductory sections
Playbook Reference docs/playbook-reference/kubernetes-examples/playbook-*.rst, docs/playbook-reference/what-are-playbooks.rst	Updated Sinks cross-reference links from "Sinks Reference" to "sinks-reference" anchor in introduction and example sections
Setup & Other docs/setup-robusta/installation/_see_robusta_in_action.rst, docs/setup-robusta/proxies.rst	Updated reST cross-reference targets from "Sinks Reference" to "sinks-reference" in notification examples

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Verify that the new "sinks-reference" anchor is properly defined in the target documentation file
• Confirm all cross-reference updates are consistent and no references to "Sinks Reference" remain orphaned
• Check that the documentation reorganization in docs/index.rst follows the intended structure

Possibly related PRs

• Update docs #1874: Modifies docs/configuration/sinks/index.rst and related sinks documentation structure changes

Suggested reviewers

• pavangudiwada
• arikalon1

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Title Check	❓ Inconclusive	The title "docs tweaks" is vague and uses a non-descriptive term that fails to convey meaningful information about the changeset. While the PR does involve documentation changes, a developer scanning commit history would not understand that the primary changes involve reorganizing the sinks documentation structure, restructuring the main index to improve navigation for alert routing topics, and updating cross-references throughout the documentation. The term "tweaks" is too generic and leaves the actual scope and purpose of the changes unclear.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	The PR description "make it easier to find and read docs on sinks and alert routing" is clearly related to the changeset. The changes reorganize the sinks documentation by renaming "Sink Reference" to "All Sinks," restructuring the main documentation index, updating cross-references, and expanding alert routing topics. These modifications directly align with the stated objective of improving documentation discoverability and readability for sinks and routing topics. The description adequately communicates the intent behind the changes.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch simplify-sinks-routing-docs

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f876a19 and dee42e0.

📒 Files selected for processing (13)

• docs/configuration/sinks/index.rst (1 hunks)
• docs/configuration/sinks/sinks-development.rst (1 hunks)
• docs/index.rst (1 hunks)
• docs/notification-routing/configuring-sinks.rst (2 hunks)
• docs/notification-routing/routing-by-namespace.rst (1 hunks)
• docs/notification-routing/routing-by-type.rst (2 hunks)
• docs/playbook-reference/kubernetes-examples/playbook-failed-liveness.rst (1 hunks)
• docs/playbook-reference/kubernetes-examples/playbook-job-failure.rst (1 hunks)
• docs/playbook-reference/kubernetes-examples/playbook-track-changes.rst (2 hunks)
• docs/playbook-reference/kubernetes-examples/playbook-track-secrets.rst (1 hunks)
• docs/playbook-reference/what-are-playbooks.rst (1 hunks)
• docs/setup-robusta/installation/_see_robusta_in_action.rst (1 hunks)
• docs/setup-robusta/proxies.rst (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: run_tests
• GitHub Check: run_tests
• GitHub Check: Deploy docs
• GitHub Check: Deploy docs

🔇 Additional comments (19)

docs/notification-routing/routing-by-namespace.rst (1)

9-9: Cross-reference anchor updated consistently.

Line 9 change aligns with the broader documentation update pattern. The syntax is correct.

docs/playbook-reference/kubernetes-examples/playbook-failed-liveness.rst (1)

4-4: Cross-reference anchor updated correctly.

The capitalized display text "Sinks" with the lowercase anchor target "sinks-reference" is appropriate usage.

docs/setup-robusta/proxies.rst (1)

7-7: Cross-reference anchor updated consistently.

The change aligns with the documentation-wide update pattern and uses correct syntax.

docs/playbook-reference/what-are-playbooks.rst (1)

15-15: Cross-reference anchor updated appropriately.

The change maintains clarity in the documentation while updating to the new anchor convention.

docs/playbook-reference/kubernetes-examples/playbook-job-failure.rst (1)

4-4: Cross-reference anchor updated consistently.

The change follows the established pattern and uses correct syntax.

docs/playbook-reference/kubernetes-examples/playbook-track-secrets.rst (1)

117-117: Cross-reference anchor updated consistently.

The change aligns with the documentation update pattern and uses correct syntax.

docs/configuration/sinks/sinks-development.rst (1)

9-9: Cross-reference anchor updated correctly.

The change is consistent with the documentation update pattern throughout the PR.

docs/notification-routing/routing-by-type.rst (1)

4-4: All references to sinks-reference are correct and complete.

The anchor sinks-reference is properly defined at docs/configuration/sinks/index.rst:1, and the cross-references in lines 4 and 14 of the reviewed file are correctly formatted. The migration to the lowercase hyphenated naming convention is consistent across the documentation with no broken links.

docs/setup-robusta/installation/_see_robusta_in_action.rst (1)

20-20: Documentation reference update aligns with PR changes.

Cross-reference updated to use the standardized sinks-reference anchor. This is consistent with changes across the documentation.

docs/playbook-reference/kubernetes-examples/playbook-track-changes.rst (2)

77-77: Documentation reference update for first use case.

Cross-reference updated consistently with PR changes to use the sinks-reference anchor.

---

136-136: Documentation reference update for second use case.

Cross-reference updated consistently with the same anchor standardization.

docs/notification-routing/configuring-sinks.rst (3)

21-21: Internal reference to existing section.

Line 21 correctly references the "All Sink Options" section defined later in the document (line 43-44).

---

87-87: Sink-specific documentation link updated.

Reference to sink-specific docs now uses the standardized sinks-reference anchor, consistent with PR changes.

---

110-110: Learn More section references updated.

The "Learn More" section at line 110 provides helpful navigation links using the standardized sinks-reference anchor for the "All Sinks" reference.

docs/configuration/sinks/index.rst (2)

1-1: Anchor definition for PR-wide standardization.

The sinks-reference anchor is correctly defined and serves as the standardized target for all sink-related cross-references throughout the documentation.

---

5-9: Improved page heading and introduction.

The heading "All Sinks" and simplified introductory text make this page's purpose clearer and more discoverable. This change aligns well with the PR objective of making sink documentation easier to find and read.

docs/index.rst (3)

52-56: Improved navigation structure for Notification Sinks section.

The section caption is now more descriptive ("Notification Sinks"), and the inclusion of both an Overview reference and an "All Sinks" hub makes the documentation structure clearer and easier to navigate. This directly supports the PR objective of improving discoverability.

---

57-79: Individual sink configuration pages now explicitly listed.

Listing all individual sink configuration pages in the main index makes them discoverable from the navigation sidebar. Verification confirms all 23 referenced sink configuration files exist in the repository.

---

81-97: New Alert Routing section with expanded routing topics is verified and approved.

All referenced Alert Routing pages exist in the repository. The addition of this dedicated section with expanded routing scenarios (namespace-based, type-based, monitoring shifts, multi-channel, exclusions, severity-based, excluding-resolved, and oomkill) improves documentation organization and aligns with the PR objective.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}