Actionable comments posted: 4

In `@docs/api/rest.md`:
- Around line 17-59: Update the REST examples to use async/await for async
methods and remove the incorrect ChannelOptions usage: change all calls to
channel.publish(...) and channel.history() to await channel.publish(...) and
history = await channel.history(); remove the import and use of ChannelOptions
(it belongs to Realtime) and instead pass cipher directly to rest.channels.get
by using cipher=CipherParams(...), e.g. channel =
rest.channels.get('encrypted-channel', cipher=cipher_params), keeping the
existing CipherParams import/constructor.

In `@docs/api/types.md`:
- Around line 1-39: Consolidate duplicate type docs by removing TokenDetails and
TokenRequest from docs/api/types.md and adding clear cross-references to their
canonical definitions in docs/api/auth.md (or vice-versa), update
docs/api/types.md to either document the abstract VCDiff interface
ably.types.options.VCDiffDecoder and also mention the concrete implementation
ably.vcdiff.default_vcdiff_decoder.AblyVCDiffDecoder (with a short note
distinguishing interface vs implementation), and normalize the ChannelOptions
entry by either changing ably.realtime.realtime_channel.ChannelOptions to the
ably.types.* pattern or adding an explicit note explaining why ChannelOptions
lives under ably.realtime.realtime_channel to keep documentation consistent.

In `@docs/index.md`:
- Around line 17-18: Update the deprecation sentence in the docs/index.md notice
that currently reads "will be deprecated from November 1, 2025" to reflect that
the date has passed by changing it to a present-tense statement such as "are
deprecated as of November 1, 2025" or "have been deprecated as of November 1,
2025"; locate and edit the exact string "SDK versions < 2.0.0-beta.6 will be
deprecated from November 1, 2025." and replace it with the preferred phrasing.

In `@pyproject.toml`:
- Around line 43-47: The docs dependency constraints in pyproject.toml are too
permissive for mkdocs-material and too restrictive for mkdocstrings; update the
docs list entries so "mkdocs-material>=9.5.32,<10.0.0; python_version>='3.8'"
replaces the current "mkdocs-material>=9.0.0,<10.0.0; python_version>='3.8'" to
exclude vulnerable releases, and change "mkdocstrings[python]>=0.24.0,<1.0.0;
python_version>='3.8'" to "mkdocstrings[python]>=0.24.0,<2.0.0;
python_version>='3.8'" to allow the stable 1.0.0 release (edit the docs = [...]
block in pyproject.toml where these dependency strings appear).

mkdocs.yml (1)

1-6: Consider updating site_url to the actual documentation hosting URL.

The site_url currently points to the GitHub repository, but it should typically point to where the documentation is actually hosted (e.g., https://ably.github.io/ably-python/ if using GitHub Pages). This affects canonical URLs and sitemap generation.

.github/workflows/docs.yml (2)

1-9: Consider adding an explicit workflow name.

The workflow lacks a name property, which makes it harder to identify in the GitHub Actions UI. The first line is a comment but not a workflow name.

Suggested improvement

 # This workflow builds the documentation and creates an artifact
+name: Documentation
 
 on:
   workflow_dispatch:

---

30-35: Consider adding restore-keys for partial cache restoration.

When uv.lock changes, the cache won't be restored at all. Adding restore-keys allows partial cache restoration, which can speed up dependency installation.

Suggested improvement

       - uses: actions/cache@v4
         name: Define a cache for the virtual environment based on the dependencies lock file
         id: cache
         with:
           path: ./.venv
           key: venv-${{ runner.os }}-3.12-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            venv-${{ runner.os }}-3.12-

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Reviewing files that changed from the base of the PR and between 7c26134 and 89d86e1.

• uv.lock is excluded by !**/*.lock

• .github/workflows/docs.yml
• .gitignore
• docs/README.md
• docs/api/auth.md
• docs/api/channels.md
• docs/api/messages.md
• docs/api/overview.md
• docs/api/realtime.md
• docs/api/rest.md
• docs/api/types.md
• docs/api/util.md
• docs/index.md
• mkdocs.yml
• pyproject.toml

[style] ~16-~16: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1600 characters long)
Context: ...ing platforms (Linux, macOS, Windows). !!! important SDK versions < 2.0.0-beta...

(EN_EXCESSIVE_EXCLAMATION)

[style] ~30-~30: Consider shortening or rephrasing this to strengthen your wording.
Context: ...lly rebuilds the documentation when you make changes to the source files. ## Documentation Str...

(MAKE_CHANGES)

• GitHub Check: check (3.9)
• GitHub Check: check (3.13)
• GitHub Check: check (3.14)
• GitHub Check: check (3.12)
• GitHub Check: check (3.10)
• GitHub Check: check (3.8)
• GitHub Check: check (3.11)

.gitignore (1)

60-60: LGTM!

Adding site/ to .gitignore is correct for MkDocs documentation builds.

docs/api/util.md (1)

25-27: No action needed. VCDiffDecoder (in ably.types.options) and AblyVCDiffDecoder (in ably.vcdiff.default_vcdiff_decoder) serve distinct purposes: the former is an abstract base class defining the interface, and the latter is the default concrete implementation that extends it. Both should be documented separately—users need to understand the interface contract and the available implementation.

Likely an incorrect or invalid review comment.

docs/api/realtime.md (1)

1-19: Realtime module paths are correct and verified.

All referenced modules and classes in the documentation exist at the correct locations:

• ably.realtime.realtime.AblyRealtime ✓
• ably.realtime.realtime_channel.Channels ✓
• ably.realtime.realtime_channel.RealtimeChannel ✓
• ably.realtime.connection.Connection ✓

No changes needed.

docs/api/auth.md (1)

10-15: Duplication confirmed: TokenDetails and TokenRequest are documented in both auth.md and types.md.

The autodoc directives for TokenDetails and TokenRequest appear in both files (auth.md lines 11, 15 and types.md lines 19, 23). This duplication mirrors a broader pattern in the documentation where core types are documented in context-specific sections (e.g., Channel/Channels appear in multiple module docs, RealtimeChannel appears twice). Consolidate if this is unintentional, or document the rationale if this contextual approach is by design.

mkdocs.yml (1)

7-77: Well-structured MkDocs configuration.

The configuration follows Material theme best practices with proper light/dark mode support, sensible navigation features, and appropriate mkdocstrings options for Python API documentation. The filter "!^_" correctly excludes private members.

docs/api/rest.md (1)

1-16: REST Client documentation structure is well-organized.

The API reference sections using mkdocstrings directives are properly structured.

docs/index.md (2)

28-52: Clear and functional quick start example.

The async context manager pattern with AblyRealtime is well-demonstrated. The example covers connection, subscription, and publishing effectively.

---

1-69: Well-structured landing page documentation.

The documentation provides a comprehensive introduction with appropriate sections for installation, quick start, features, and support links. The content aligns well with SDK documentation best practices.

docs/api/messages.md (1)

1-37: Comprehensive and accurate message types documentation.

All referenced message types and operations are correctly documented with proper module paths. The coverage of core message functionality, mutable message operations (update, delete, append), and presence messaging is well-structured and complete.

docs/api/channels.md (1)

1-27: Documentation structure and module paths are correct.

All referenced modules and classes exist in the codebase with the correct module paths:

• ably.rest.channel.Channels and ably.rest.channel.Channel in ./ably/rest/channel.py
• ably.realtime.realtime_channel.Channels and ably.realtime.realtime_channel.RealtimeChannel in ./ably/realtime/realtime_channel.py
• ably.realtime.realtimepresence.RealtimePresence in ./ably/realtime/realtimepresence.py

docs/api/overview.md (1)

1-82: LGTM!

The API reference overview is well-structured with clear hierarchy, appropriate navigation links to related documentation pages, and concise descriptions of core clients and components.

docs/README.md (1)

1-52: LGTM!

Clear and comprehensive documentation for building and serving the docs locally. The instructions align well with the CI workflow and explain the mkdocstrings integration effectively.

.github/workflows/docs.yml (1)

37-48: LGTM!

The dependency installation, build, and upload steps are correctly configured and align with the documentation instructions.

✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.

Actionable comments posted: 1

In @.github/workflows/docs.yml:
- Around line 3-9: The workflow currently triggers on pull_request, push and
workflow_dispatch, but the AWS credential configuration and upload steps run for
PRs (causing secret/role failures for forks); update the job or those specific
steps (the AWS credential setup and the S3/upload steps referenced in the PR
comment) to only execute when the event is not a pull_request by adding a
conditional such as if: github.event_name != 'pull_request' (or if:
github.event.pull_request == null) on the steps or job, so AWS secrets are only
used on push/workflow_dispatch events.

pyproject.toml (1)

43-47: Re‑verify docs dependency version bounds (security + compatibility).
Please re-check current advisories and latest stable releases for MkDocs tooling and adjust bounds if needed (e.g., raise minimums for patched versions and consider allowing mkdocstrings 1.x if stable).

Possible update (if verification supports it)

 docs = [
   "mkdocs>=1.5.0,<2.0.0; python_version>='3.8'",
-  "mkdocs-material>=9.0.0,<10.0.0; python_version>='3.8'",
-  "mkdocstrings[python]>=0.24.0,<1.0.0; python_version>='3.8'",
+  "mkdocs-material>=9.5.32,<10.0.0; python_version>='3.8'",
+  "mkdocstrings[python]>=0.24.0,<2.0.0; python_version>='3.8'",
 ]

Please verify via:

latest mkdocs-material security advisories minimum patched version

mkdocstrings python latest stable version 1.x compatibility

docs/index.md (1)

17-18: Update deprecation tense to reflect the past date.
This notice references a date already in the past; tweak the tense to avoid confusion.

Suggested fix

 !!! important
-    SDK versions < 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025.
+    SDK versions < 2.0.0-beta.6 are [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) as of November 1, 2025.

.github/workflows/docs.yml (1)

19-31: Pin GitHub Actions to commit SHAs for supply‑chain hardening.

Using moving tags (@v4, @v5, etc.) allows upstream changes without review. Consider pinning to specific SHAs and updating intentionally.

🔒 Example pattern

-      - uses: actions/checkout@v4
+      - uses: actions/checkout@<pinned-sha> # v4.x.x

Apply the same approach to actions/setup-python, astral-sh/setup-uv, actions/cache, aws-actions/configure-aws-credentials, and ably/sdk-upload-action.

Also applies to: 34-35, 48-55

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Reviewing files that changed from the base of the PR and between 89d86e1 and cb2040e.

• uv.lock is excluded by !**/*.lock

• .github/workflows/docs.yml
• .gitignore
• docs/README.md
• docs/api/auth.md
• docs/api/channels.md
• docs/api/messages.md
• docs/api/overview.md
• docs/api/realtime.md
• docs/api/rest.md
• docs/api/types.md
• docs/api/util.md
• docs/index.md
• mkdocs.yml
• pyproject.toml

• docs/api/realtime.md
• docs/api/messages.md
• docs/api/rest.md

• docs/api/auth.md
• docs/api/util.md
• mkdocs.yml
• docs/api/channels.md
• .gitignore

[style] ~30-~30: Consider shortening or rephrasing this to strengthen your wording.
Context: ...lly rebuilds the documentation when you make changes to the source files. ## Documentation Str...

(MAKE_CHANGES)

[style] ~16-~16: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1600 characters long)
Context: ...ing platforms (Linux, macOS, Windows). !!! important SDK versions < 2.0.0-beta...

(EN_EXCESSIVE_EXCLAMATION)

• GitHub Check: check (3.14)
• GitHub Check: check (3.11)
• GitHub Check: check (3.12)
• GitHub Check: check (3.8)
• GitHub Check: check (3.13)
• GitHub Check: check (3.10)
• GitHub Check: check (3.9)
• GitHub Check: docs

docs/api/types.md (1)

1-39: Docs structure looks good for mkdocstrings.

docs/README.md (1)

1-52: Clear setup and usage guidance.

docs/api/overview.md (1)

1-82: Overview reads well and links are coherent.

.github/workflows/docs.yml (1)

41-45: Docs build flow looks good.

uv sync --extra docs followed by uv run mkdocs build is clear and keeps docs deps isolated.

✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.

Actionable comments posted: 1

In `@docs/api/rest.md`:
- Around line 1-3: Update the REST client documentation header to state the
client provides asynchronous (not synchronous) access; replace the phrase
"synchronous access" with "asynchronous access" and optionally note that major
methods such as publish(), history(), stats(), and other API methods are async
and should be awaited so readers understand the need to use await with these
functions.

.github/workflows/docs.yml (1)

47-59: Skip AWS publish steps on pull requests to avoid failures.

The AWS credentials configuration and upload steps will fail for fork PRs (secrets unavailable) and shouldn't publish unmerged documentation. Add a condition to skip these steps on pull request events.

🛠️ Suggested fix

       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v4
+        if: github.event_name != 'pull_request'
         with:
           aws-region: eu-west-2
           role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-python
           role-session-name: "${{ github.run_id }}-${{ github.run_number }}"

       - name: Upload Documentation
         uses: ably/sdk-upload-action@v2
+        if: github.event_name != 'pull_request'
         with:
           sourcePath: site/
           githubToken: ${{ secrets.GITHUB_TOKEN }}
           artifactName: docs

.github/workflows/docs.yml (1)

34-39: Consider using restore-keys for cache fallback.

The cache key is specific to the exact uv.lock hash. Adding restore-keys would allow partial cache hits when dependencies change slightly, improving cache utilization.

💡 Suggested improvement

       - uses: actions/cache@v4
         name: Define a cache for the virtual environment based on the dependencies lock file
         id: cache
         with:
           path: ./.venv
           key: venv-${{ runner.os }}-3.12-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            venv-${{ runner.os }}-3.12-

some other questions:

• if we're sticking with mkdocs i think we need to at least resolve all the build warnings emitted when building the docs. currently there are a lot
• there's a few weird artefacts in the static website like having no linebreaks or separators between method params: