[AIT-289] docs: add autogenerated API references docs #661
Conversation
WalkthroughAdds a MkDocs-based documentation site (content, config, and deps), a GitHub Actions workflow to build and publish the site (with AWS role assumption and artifact upload), and updates VCS ignore to exclude generated Changes
Sequence Diagram(s)sequenceDiagram
participant Developer
participant GH_Actions as GH Actions Runner
participant PythonEnv as Python 3.12 Env
participant UV as uv Tool
participant AWS as AWS STS/IAM
participant AblyUpload as ably/sdk-upload-action
Developer->>GH_Actions: Trigger workflow (push/PR/dispatch)
GH_Actions->>GH_Actions: checkout repo (with submodules)
GH_Actions->>PythonEnv: setup-python 3.12
GH_Actions->>UV: install deps (uv sync --extra docs)
GH_Actions->>PythonEnv: run build (uv run mkdocs build)
GH_Actions->>AWS: configure-aws-credentials (assume role)
GH_Actions->>AblyUpload: upload artifact `site/` with assumed creds
AblyUpload->>AWS: use assumed role credentials to store/upload artifact
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro Disabled knowledge base sources:
⛔ Files ignored due to path filters (1)
📒 Files selected for processing (14)
✅ Files skipped from review due to trivial changes (2)
🚧 Files skipped from review as they are similar to previous changes (7)
🧰 Additional context used🪛 LanguageTooldocs/README.md[style] ~30-~30: Consider shortening or rephrasing this to strengthen your wording. (MAKE_CHANGES) docs/index.md[style] ~16-~16: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1600 characters long) (EN_EXCESSIVE_EXCLAMATION) ⏰ 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). (7)
🔇 Additional comments (3)
✏️ Tip: You can disable this entire section by setting 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 |
github-actions
bot
temporarily deployed
to
staging/pull/661/features
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
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).
🧹 Nitpick comments (3)
mkdocs.yml (1)
1-6: Consider updatingsite_urlto the actual documentation hosting URL.The
site_urlcurrently 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
nameproperty, 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 addingrestore-keysfor partial cache restoration.When
uv.lockchanges, the cache won't be restored at all. Addingrestore-keysallows 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-
📜 Review details
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.
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (14)
.github/workflows/docs.yml.gitignoredocs/README.mddocs/api/auth.mddocs/api/channels.mddocs/api/messages.mddocs/api/overview.mddocs/api/realtime.mddocs/api/rest.mddocs/api/types.mddocs/api/util.mddocs/index.mdmkdocs.ymlpyproject.toml
🧰 Additional context used
🪛 LanguageTool
docs/index.md
[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)
docs/README.md
[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)
⏰ 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). (7)
- 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)
🔇 Additional comments (13)
.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(inably.types.options) andAblyVCDiffDecoder(inably.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
TokenDetailsandTokenRequestappear 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
AblyRealtimeis 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.Channelsandably.rest.channel.Channelin./ably/rest/channel.pyably.realtime.realtime_channel.Channelsandably.realtime.realtime_channel.RealtimeChannelin./ably/realtime/realtime_channel.pyably.realtime.realtimepresence.RealtimePresencein./ably/realtime/realtimepresence.pydocs/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.
| ## Examples | ||
|
|
||
| ### Basic Usage | ||
|
|
||
| ```python | ||
| from ably import AblyRest | ||
|
|
||
| # Initialize the REST client | ||
| rest = AblyRest('your-api-key') | ||
|
|
||
| # Get a channel | ||
| channel = rest.channels.get('test-channel') | ||
|
|
||
| # Publish a message | ||
| channel.publish('event-name', {'key': 'value'}) | ||
|
|
||
| # Get channel history | ||
| history = channel.history() | ||
| for message in history.items: | ||
| print(f'Message: {message.data}') | ||
| ``` | ||
|
|
||
| ### Publishing Multiple Messages | ||
|
|
||
| ```python | ||
| # Publish multiple messages at once | ||
| channel.publish([ | ||
| {'name': 'event-1', 'data': 'first message'}, | ||
| {'name': 'event-2', 'data': 'second message'}, | ||
| ]) | ||
| ``` | ||
|
|
||
| ### Using Channel Options | ||
|
|
||
| ```python | ||
| from ably.types.options import ChannelOptions | ||
| from ably.util.crypto import CipherParams | ||
|
|
||
| # Get a channel with encryption | ||
| cipher_params = CipherParams(secret_key='your-secret-key') | ||
| options = ChannelOptions(cipher=cipher_params) | ||
| channel = rest.channels.get('encrypted-channel', options) | ||
| ``` No newline at end of file |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the CipherParams class and its constructor parameters
echo "=== Checking for crypto module ==="
fd -e py 'crypto' --type f
echo "=== Checking CipherParams class definition ==="
rg -n "class CipherParams" --type py -A 10
echo "=== Checking ChannelOptions class ==="
rg -n "class ChannelOptions" --type py -A 10
echo "=== Checking channel.publish method signature ==="
rg -n "def publish" --type py -A 5 | head -50
echo "=== Checking channel.history method signature ==="
rg -n "def history" --type py -A 5 | head -50Repository: ably/ably-python
Length of output: 6247
🏁 Script executed:
#!/bin/bash
# Check for ChannelOptions in types/options
echo "=== Checking for ably/types/options.py ==="
fd -n "options.py" --type f
echo "=== Checking ChannelOptions imports in examples/docs ==="
rg -n "from ably.*options import" --type py
echo "=== Checking if ChannelOptions exists in multiple locations ==="
rg -n "class ChannelOptions" --type py
echo "=== Checking REST client for synchronous vs async ==="
rg -n "class AblyRest" --type py -A 20
echo "=== Checking publish method more thoroughly ==="
rg -B5 -A15 "async def publish" ably/rest/channel.pyRepository: ably/ably-python
Length of output: 4534
🏁 Script executed:
#!/bin/bash
echo "=== Checking REST channel.get() method ==="
rg -B5 -A10 "def get" ably/rest/channels.py | head -50
echo "=== Checking if REST ChannelOptions is used ==="
rg -n "ChannelOptions" ably/rest/ --type py
echo "=== Checking test examples for REST channel usage ==="
rg -B3 -A3 "channels.get" test/ably/rest/ --type py | head -60
echo "=== Checking if publish/history work in sync context ==="
rg -B2 -A2 "rest_channel_publish_test" test/ --type py | head -30Repository: ably/ably-python
Length of output: 4984
🏁 Script executed:
#!/bin/bash
echo "=== Finding channels implementation ==="
fd "channels" --type f --path "*/rest/*" | grep -v test
echo "=== Checking channels class ==="
rg -n "class.*[Cc]hannels" ably/rest/ --type py -A 10
echo "=== Checking get method in channels ==="
rg -n "def get" ably/rest/ --type py -B 2 -A 8Repository: ably/ably-python
Length of output: 4519
🏁 Script executed:
#!/bin/bash
echo "=== Checking Channel class constructor ==="
rg -B5 -A15 "class Channel:" ably/rest/channel.py | head -50
echo "=== Checking Channel __init__ ==="
rg -B2 -A20 "def __init__" ably/rest/channel.py | head -40Repository: ably/ably-python
Length of output: 2239
Fix code examples to use async/await and remove incorrect ChannelOptions usage.
The documentation examples have several API accuracy issues:
- Both
channel.publish()andchannel.history()are async methods but examples don't useawait—this will cause runtime errors. - The import
from ably.types.options import ChannelOptionsis incorrect—ChannelOptionsonly exists in the Realtime module and isn't available in the REST API. - For REST channels with encryption, pass
cipherdirectly tochannels.get(), not wrapped inChannelOptions:
# Correct pattern for encryption with REST channels
cipher_params = CipherParams(secret_key='your-secret-key')
channel = rest.channels.get('encrypted-channel', cipher=cipher_params)
# Use await for async methods
await channel.publish('event-name', {'key': 'value'})
history = await channel.history()The CipherParams import path and constructor parameter are correct.
🤖 Prompt for AI Agents
In `@docs/api/rest.md` around lines 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.
| # Types | ||
|
|
||
| Core data types and configuration options. | ||
|
|
||
| ## Client Options | ||
|
|
||
| ::: ably.types.options.Options | ||
|
|
||
| ## Auth Options | ||
|
|
||
| ::: ably.types.authoptions.AuthOptions | ||
|
|
||
| ## Channel Options | ||
|
|
||
| ::: ably.realtime.realtime_channel.ChannelOptions | ||
|
|
||
| ## Token Details | ||
|
|
||
| ::: ably.types.tokendetails.TokenDetails | ||
|
|
||
| ## Token Request | ||
|
|
||
| ::: ably.types.tokenrequest.TokenRequest | ||
|
|
||
| ## Stats | ||
|
|
||
| ::: ably.types.stats.Stats | ||
|
|
||
| ## Device Details | ||
|
|
||
| ::: ably.types.device.DeviceDetails | ||
|
|
||
| ## Push Channel Subscription | ||
|
|
||
| ::: ably.types.channelsubscription.PushChannelSubscription | ||
|
|
||
| ## VCDiff Decoder | ||
|
|
||
| ::: ably.types.options.VCDiffDecoder No newline at end of file |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# First, check if the ably package is available in the repo
git ls-files | head -20Repository: ably/ably-python
Length of output: 176
🏁 Script executed:
# Find documentation and source files
find . -type f -name "*.md" | grep -E "(types|auth|util)" | head -20Repository: ably/ably-python
Length of output: 117
🏁 Script executed:
# Check the source code structure
find . -type d -name "ably" | head -5Repository: ably/ably-python
Length of output: 78
🏁 Script executed:
# Check the content of types.md
cat docs/api/types.mdRepository: ably/ably-python
Length of output: 651
🏁 Script executed:
# Check the content of auth.md to look for duplication
cat docs/api/auth.mdRepository: ably/ably-python
Length of output: 384
🏁 Script executed:
# Check the content of util.md to see VCDiff reference
cat docs/api/util.mdRepository: ably/ably-python
Length of output: 525
🏁 Script executed:
# Check the ably directory structure
ls -la ./ably/Repository: ably/ably-python
Length of output: 739
🏁 Script executed:
# Check if VCDiffDecoder exists in ably.types.options
find ./ably/types -name "*.py" | xargs grep -l "VCDiffDecoder" 2>/dev/nullRepository: ably/ably-python
Length of output: 83
🏁 Script executed:
# Check the vcdiff module structure
ls -la ./ably/vcdiff/Repository: ably/ably-python
Length of output: 310
🏁 Script executed:
# Look for TokenDetails and TokenRequest in types
ls -la ./ably/types/ | grep -E "(token|Token)"Repository: ably/ably-python
Length of output: 193
🏁 Script executed:
# Check the realtime directory for ChannelOptions
ls -la ./ably/realtime/Repository: ably/ably-python
Length of output: 710
🏁 Script executed:
# Search for VCDiffDecoder class definition
grep -r "class VCDiffDecoder" ./ably/ 2>/dev/nullRepository: ably/ably-python
Length of output: 109
🏁 Script executed:
# Search for AblyVCDiffDecoder class definition
grep -r "class AblyVCDiffDecoder" ./ably/ 2>/dev/nullRepository: ably/ably-python
Length of output: 139
🏁 Script executed:
# Check if ChannelOptions exists in realtime_channel.py
grep -n "class ChannelOptions" ./ably/realtime/realtime_channel.pyRepository: ably/ably-python
Length of output: 84
🏁 Script executed:
# Check if there's a ChannelOptions in types directory
find ./ably/types -name "*.py" | xargs grep -l "ChannelOptions" 2>/dev/nullRepository: ably/ably-python
Length of output: 44
🏁 Script executed:
# View the VCDiffDecoder class from options.py
sed -n '/^class VCDiffDecoder/,/^class /p' ./ably/types/options.py | head -30Repository: ably/ably-python
Length of output: 704
🏁 Script executed:
# View the AblyVCDiffDecoder class from default_vcdiff_decoder.py
sed -n '/^class AblyVCDiffDecoder/,/^class /p' ./ably/vcdiff/default_vcdiff_decoder.py | head -30Repository: ably/ably-python
Length of output: 975
Address documentation duplication and VCDiff decoder discrepancy.
-
Duplicate documentation:
TokenDetailsandTokenRequestare documented in bothdocs/api/types.mdanddocs/api/auth.md. Consider consolidating or removing one instance to avoid redundancy. -
VCDiff decoder inconsistency:
docs/api/types.mddocumentsably.types.options.VCDiffDecoder(an abstract base class), whiledocs/api/util.mddocumentsably.vcdiff.default_vcdiff_decoder.AblyVCDiffDecoder(the concrete implementation). Clarify which class should be featured in the types documentation, or document both with clear distinction between the interface and implementation. -
ChannelOptions module path: The path
ably.realtime.realtime_channel.ChannelOptionsis correct but inconsistent with theably.types.*pattern used for other documented types. Document consistently or add a note explaining the different module organization.
🤖 Prompt for AI Agents
In `@docs/api/types.md` around lines 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.
| !!! important | ||
| SDK versions < 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025. |
There was a problem hiding this comment.
Deprecation date has passed.
The deprecation notice states SDK versions < 2.0.0-beta.6 will be deprecated from November 1, 2025. Since we're now past that date, consider updating this notice to reflect the current status (e.g., "are deprecated as of November 1, 2025" or "have been deprecated").
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.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| !!! important | |
| SDK versions < 2.0.0-beta.6 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025. | |
| !!! important | |
| SDK versions < 2.0.0-beta.6 are [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) as of November 1, 2025. |
🤖 Prompt for AI Agents
In `@docs/index.md` around lines 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.
| 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'", | ||
| ] |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check latest versions of documentation dependencies on PyPI
echo "=== Checking mkdocs ==="
curl -s https://pypi.org/pypi/mkdocs/json | jq -r '.info | "Current version: \(.version)"'
echo "=== Checking mkdocs-material ==="
curl -s https://pypi.org/pypi/mkdocs-material/json | jq -r '.info | "Current version: \(.version)"'
echo "=== Checking mkdocstrings ==="
curl -s https://pypi.org/pypi/mkdocstrings/json | jq -r '.info | "Current version: \(.version)"'Repository: ably/ably-python
Length of output: 215
🌐 Web query:
mkdocs mkdocs-material mkdocstrings security advisories CVE
💡 Result:
Brief summary of recent/security-relevant advisories for MkDocs, Material for MkDocs, and related plugins (mkdocstrings / include-plugins):
-
mkdocs-material (Python theme)
- Cross-site scripting (XSS) in versions < 9.5.32 — fixed by upgrading to 9.5.32+. [1]
- Reports of malicious/typo-squat npm packages claiming the mkdocs-material name were published in Mar 2025 (avoid malicious packages from untrusted registries). [2][3]
-
MkDocs core
- Historical XSS / search-related issues and a dev-server directory-traversal issue have been reported previously; upgrade to recent MkDocs releases when advisories say to do so. [4]
-
mkdocs-include-markdown-plugin
- CVE‑2025‑59940 (input/placeholder collision / improper neutralization) affecting versions ≤ 7.1.7 — fixed in 7.1.8; upgrade recommended. (NVD / Snyk / vendor PRs). [5][6][7]
-
mkdocstrings
- Open discussions/issues about sanitizing Markdown / preventing JS execution in generated docs — follow upstream issue and ensure you sanitize or review rendered content. [8]
Recommended actions
- Immediately upgrade affected packages to the fixed versions noted above (mkdocs-material → ≥ 9.5.32; mkdocs-include-markdown-plugin → ≥ 7.1.8; keep MkDocs/mkdocstrings up to date). [1][5]
- Audit dependencies for typo-squat/malicious packages from untrusted registries and prefer official PyPI releases or the project's releases page. [2][3]
- Sanitize/inspect any user-supplied Markdown/docstrings before publishing (to mitigate XSS / JS execution risks). [8]
Sources
- Snyk — mkdocs-material XSS advisory.
- Snyk / report on malicious mkdocs-material npm package (Mar 2025).
- Vulert / mkdocs-material malicious-package report.
- Snyk / MkDocs XSS and related advisories.
- NVD entry CVE‑2025‑59940 (mkdocs-include-markdown-plugin).
- Snyk advisory for mkdocs-include-markdown-plugin (CVE‑2025‑59940).
- OpenCVE / Open sources and vendor GitHub PR references for the include-markdown fix.
- mkdocstrings GitHub issue discussing Markdown sanitization.
If you want, I can:
- check the exact installed versions in your project (send your requirements.txt / pyproject.lock), or
- provide exact upgrade commands and a short CI scan script to detect these packages.
Update version constraints to exclude vulnerable mkdocs-material versions and allow mkdocstrings 1.0.0.
The constraint for mkdocstrings[python]>=0.24.0,<1.0.0 prevents using the stable 1.0.0 release now available on PyPI (current: 1.0.0). Update the upper bound to <2.0.0.
Additionally, the mkdocs-material>=9.0.0,<10.0.0 constraint allows vulnerable versions below 9.5.32 (XSS vulnerability reported). Update the minimum version to >=9.5.32 to enforce the security fix.
Recommended updates:
mkdocs-material>=9.5.32,<10.0.0; python_version>='3.8'mkdocstrings[python]>=0.24.0,<2.0.0; python_version>='3.8'
🤖 Prompt for AI Agents
In `@pyproject.toml` around lines 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).
ttypic
force-pushed
the
AIT-289/api-docs
branch
from
89d86e1 to
cb2040e
Compare
github-actions
bot
temporarily deployed
to
staging/pull/661/features
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
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.
♻️ Duplicate comments (2)
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 versionmkdocstrings python latest stable version 1.x compatibilitydocs/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.
🧹 Nitpick comments (1)
.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.xApply the same approach to
actions/setup-python,astral-sh/setup-uv,actions/cache,aws-actions/configure-aws-credentials, andably/sdk-upload-action.Also applies to: 34-35, 48-55
📜 Review details
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.
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (14)
.github/workflows/docs.yml.gitignoredocs/README.mddocs/api/auth.mddocs/api/channels.mddocs/api/messages.mddocs/api/overview.mddocs/api/realtime.mddocs/api/rest.mddocs/api/types.mddocs/api/util.mddocs/index.mdmkdocs.ymlpyproject.toml
✅ Files skipped from review due to trivial changes (3)
- docs/api/realtime.md
- docs/api/messages.md
- docs/api/rest.md
🚧 Files skipped from review as they are similar to previous changes (5)
- docs/api/auth.md
- docs/api/util.md
- mkdocs.yml
- docs/api/channels.md
- .gitignore
🧰 Additional context used
🪛 LanguageTool
docs/README.md
[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)
docs/index.md
[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)
⏰ 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). (8)
- 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
🔇 Additional comments (4)
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 docsfollowed byuv run mkdocs buildis clear and keeps docs deps isolated.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| on: | ||
| workflow_dispatch: | ||
| pull_request: | ||
| push: | ||
| branches: | ||
| - main | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name "docs.yml" -path ".github/workflows/*" -type fRepository: ably/ably-python
Length of output: 42
🏁 Script executed:
ls -la .github/workflows/ 2>/dev/null || echo "Directory not found"Repository: ably/ably-python
Length of output: 469
🏁 Script executed:
cat -n .github/workflows/docs.ymlRepository: ably/ably-python
Length of output: 2005
Skip AWS publish steps on PRs to avoid secret/role failures.
This job runs on pull_request, but the AWS credentials (lines 47–52) and upload steps (lines 54–59) will fail for forks (no secrets available) and shouldn't publish from unmerged code. Gate those steps to non‑PR events.
🛠️ Proposed 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-chat-kotlin
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🤖 Prompt for AI Agents
In @.github/workflows/docs.yml around lines 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.
cb2040e to
b516a2d
Compare
github-actions
bot
temporarily deployed
to
staging/pull/661/features
ttypic
force-pushed
the
AIT-289/api-docs
branch
from
b516a2d to
ac87578
Compare
autogenerated API references docs using MkDocs
Summary by CodeRabbit
New Features
Chores
✏️ Tip: You can customize this high-level summary in your review settings.