[DX-955] Add use-case based SDK references across Pub/Sub pages#3340
[DX-955] Add use-case based SDK references across Pub/Sub pages#3340
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
sacOO7
changed the title
sacOO7
changed the title
There was a problem hiding this comment.
Pull request overview
Updates Ably documentation to steer developers toward purpose-built SDKs (Chat/Spaces) for common realtime features, while positioning Pub/Sub as the underlying primitive for custom use cases and adding/fixing cross-links for smoother navigation.
Changes:
- Adds Chat SDK / Spaces SDK cross-references and guidance asides across Pub/Sub, Presence/Occupancy, Messages, and Spaces docs.
- Fixes broken anchors/links and converts legacy Textile-style links to standard MDX link syntax.
- Standardizes example channel naming (e.g.,
chatroom→my-channel) and replaces placeholder API keys with template variables.
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/pages/docs/spaces/index.mdx | Reframes “enhancements” to point to purpose-built SDKs and product guidance. |
| src/pages/docs/pub-sub/guides/data-streaming.mdx | Adds Chat SDK guidance aside, fixes broken stats anchor, and updates example API key placeholders. |
| src/pages/docs/pub-sub/guides/dashboards-and-visualizations.mdx | Fixes channel attach/detach links, updates persistence anchor, templatises credentials, and adds SDK guidance asides. |
| src/pages/docs/pub-sub/advanced.mdx | Renames example channel identifiers and wraps subscription filters notice in a consistent public preview aside; adds an anchor for headers section. |
| src/pages/docs/presence-occupancy/presence.mdx | Adds Chat/Spaces guidance, updates examples to use neutral channel names, and adds an avatar stack cross-link. |
| src/pages/docs/presence-occupancy/index.mdx | Adds Chat SDK guidance note and links “chat application” to Chat docs. |
| src/pages/docs/messages/updates-deletes.mdx | Adds guidance to prefer Chat SDK editing/moderation APIs for chat contexts. |
| src/pages/docs/messages/annotations.mdx | Adds Chat SDK cross-references and introduces an “interactions” anchor; clarifies intent for non-chat Pub/Sub use. |
| src/pages/docs/faq/push-faqs.mdx | Fixes broken publish anchors by pointing to Pub/Sub publish section. |
| src/pages/docs/chat/rooms/message-reactions.mdx | Fixes “PubSub” naming to “Pub/Sub” for consistency. |
| src/pages/docs/channels/states.mdx | Updates channel name examples to avoid implying Pub/Sub channels are “chat rooms.” |
| src/pages/docs/channels/options/rewind.mdx | Adds pointer to Chat SDK history for chat-room-style history use cases. |
| src/pages/docs/channels/options/echo.mdx | Adds Chat SDK link for chat application example reference. |
| src/pages/docs/channels/index.mdx | Converts legacy Textile links to MDX and updates persistence link target. |
| src/pages/docs/basics/index.mdx | Positions presence as the underlying primitive for Spaces/Chat features; links to product guidance. |
| src/pages/docs/auth/token/jwt.mdx | Updates JWT examples to use neutral channel names instead of chat-specific ones. |
| src/pages/docs/auth/identified-clients.mdx | Links chat application example reference to Chat docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…sections # Conflicts: # src/pages/docs/channels/index.mdx # src/pages/docs/channels/options/rewind.mdx
|
@claude review |
There was a problem hiding this comment.
Pull request overview
Updates Pub/Sub-related documentation to guide developers toward purpose-built SDKs (Chat/Spaces) for common chat/collaboration use cases, while positioning Pub/Sub as the underlying primitive and the option for custom features. Also fixes several broken links/anchors and modernizes examples/formatting for consistency across the docs site.
Changes:
- Added cross-references to Chat SDK / Spaces SDK across Pub/Sub, Presence/Occupancy, Messages, and Spaces docs to prevent “build chat from scratch on Pub/Sub” guidance.
- Fixed broken anchors/links and updated a preview notice to use consistent
<Aside>formatting. - Standardized examples (channel names and API key template variables) and corrected a few minor text/link issues.
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| src/pages/docs/spaces/index.mdx | Reframes “enhancing Spaces apps” to recommend Chat SDK / Pub/Sub appropriately and links product guidance. |
| src/pages/docs/pub-sub/guides/data-streaming.mdx | Adds Chat SDK guidance note, fixes stats anchor, corrects a broken relative link, and replaces API key placeholders with templates. |
| src/pages/docs/pub-sub/guides/dashboards-and-visualizations.mdx | Fixes attach/detach links, adds a stable anchor, updates persistence anchor, switches API keys to templates, and adds SDK guidance asides. |
| src/pages/docs/pub-sub/advanced.mdx | Replaces chat-themed channel names with neutral names; wraps subscription-filters notice in a public-preview Aside; adds an explicit headers anchor. |
| src/pages/docs/presence-occupancy/presence.mdx | Adds Chat/Spaces guidance asides and links; neutralizes channel naming in multi-language examples; adds Spaces avatar stack reference. |
| src/pages/docs/presence-occupancy/index.mdx | Adds Chat SDK cross-links and guidance for presence/occupancy examples. |
| src/pages/docs/messages/updates-deletes.mdx | Adds Chat SDK cross-reference for message editing/moderation vs Pub/Sub updates/deletes. |
| src/pages/docs/messages/annotations.mdx | Adds Chat SDK cross-reference for reactions/read receipts/moderation; adds an interactions anchor and clarifies “reactions” bullet. |
| src/pages/docs/faq/push-faqs.mdx | Fixes broken publish links by pointing to the Push “publish via channels” section. |
| src/pages/docs/chat/rooms/message-reactions.mdx | Links “Pub/Sub annotations” mention to the annotations docs page for clarity. |
| src/pages/docs/channels/states.mdx | Replaces chat-themed channel names with neutral names across attach/detach/state examples. |
| src/pages/docs/channels/options/rewind.mdx | Removes chat-room-specific framing from rewind description. |
| src/pages/docs/channels/options/echo.mdx | Adds Chat/Spaces contextual links in the echo explanation. |
| src/pages/docs/channels/index.mdx | Fixes grammar in the “message annotations/updates/deletes/appends” rule description. |
| src/pages/docs/basics/index.mdx | Reframes presence as the primitive underlying Spaces avatar stacks and Chat presence, with product guidance link. |
| src/pages/docs/auth/token/jwt.mdx | Neutralizes channel naming in JWT capability/channel-claim example. |
| src/pages/docs/auth/identified-clients.mdx | Adds Chat docs link in the example narrative. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
kennethkalmer
left a comment
kennethkalmer
left a comment
There was a problem hiding this comment.
Soft ✅ from me, this is great work @sacOO7. I think the extensive copy updates need a second pair of eyes, but I can see from the example code updates you did exactly how an LLM would arrive at the fact that you build chat with Pub/Sub, so thanks for cleaning it up.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…abilities - Drop trailing slash on /docs/spaces link in echo channel option page - Rewrite "differential token capabilities on a single channel" example to actually use a single channel, split across publisher/subscriber tokens
sacOO7
force-pushed
the
fix/incorrect-pubsub-sections
branch
from
b909259 to
531980e
Compare
Changes
SDK cross-references (prevent misguided implementations):
basics, data streaming guide, and dashboards guide pages
to the appropriate SDK docs
Broken links fixed:
/docs/channels#publish→/docs/pub-sub#publishin push FAQs (2 instances)/docs/storage-history/storage#persistence→/docs/storage-history/storage#all-message-persistencein dashboards guide
/docs/metadata-stats/stats#live→/docs/metadata-stats/stats#app-metain data streaming guide"text":/path) → MDX links ([text](/path)) in channels index, plus typo fixNaming and consistency:
chatroom/private:chatroomchannel names withmy-channel/private:my-channelacrosschannel states (~20 instances) and Pub/Sub advanced (~20 instances) to avoid implying Pub/Sub
channels are for building chat
your-api-key,YOUR_API_KEY_NAME) with template variables(
{{API_KEY}},{{API_KEY_NAME}},{{API_KEY_SECRET}}) in both Pub/Sub guidesStale notice:
<Aside data-type='public-preview'>block for consistency