docs: improve Python SDK API reference with field descriptions and fix doc generator#1312
Open
docs: improve Python SDK API reference with field descriptions and fix doc generator#1312
Conversation
…cumentation - Refactored SDK initialization to use `register_worker` across examples. - Updated method signatures and documentation for clarity and consistency. - Enhanced docstrings with attribute descriptions for better understanding. - Improved example formatting in documentation for better readability.
- Eliminated references to the async `greet_async` function in both the documentation and code examples for clarity. - Streamlined the `greet` function example by removing unnecessary lines, enhancing readability.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthroughThis PR updates documentation, type definitions, and parsing logic to reflect API migration from class-based initialization (III) to function-based patterns (register_worker) with InitOptions, and converts trigger/function registration from positional arguments to dictionary-based inputs across Python and Rust SDKs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
📝 Coding Plan
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/content/api-reference/sdk-python.mdx`:
- Line 174: The docs show an incorrect type for the parameter named callback;
update the type to the correct signature Callable[[list[FunctionInfo]], None]
(as implemented in iii.py around line 1018) and fix the doc-generator logic in
parse-griffe.mts so it does not truncate callable signatures—ensure
parse-griffe.mts preserves parameterized Callable types when extracting
annotations so the rendered table entry for callback becomes
`Callable[[list[FunctionInfo]], None]`.
In `@sdk/packages/python/iii/src/iii/iii_types.py`:
- Around line 474-476: The Field description for the direction attribute in
iii_types.py is inconsistent with its type: the Literal is defined as "read" |
"write" but the description says "reader" or "writer"; update the description on
the direction Field (symbol: direction) to accurately state "read or write" (or
alternatively change the Literal values to "reader"/"writer" if those are the
intended values) so the docstring matches the actual type.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 667412c7-eb86-4f8e-a2e6-adc1b287a911
📒 Files selected for processing (6)
docs/content/api-reference/iii-sdk.mdxdocs/content/api-reference/sdk-python.mdxdocs/scripts/parsers/parse-griffe.mtssdk/packages/python/iii/src/iii/iii.pysdk/packages/python/iii/src/iii/iii_constants.pysdk/packages/python/iii/src/iii/iii_types.py
| | Name | Type | Required | Description | | ||
| | --- | --- | --- | --- | | ||
| | `callback` | `Callable[None]` | Yes | Receives the current list of ``FunctionInfo`` objects each time availability changes. | | ||
| | `callback` | `Callable[None]` | Yes | - | |
Contributor
There was a problem hiding this comment.
Incorrect callback type signature.
The type Callable[None] is incorrect. Per the source code in iii.py line 1018, the actual signature is Callable[[list[FunctionInfo]], None]. The doc generator appears to be truncating the callable type.
📝 Proposed fix
-| `callback` | `Callable[None]` | Yes | - |
+| `callback` | `Callable[[list[FunctionInfo]], None]` | Yes | Receives the current list of ``FunctionInfo`` objects each time availability changes. |Note: This may require a fix in the doc generator (parse-griffe.mts) to properly extract callable type signatures.
📝 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.
Suggested change
| | `callback` | `Callable[None]` | Yes | - | | |
| | `callback` | `Callable[[list[FunctionInfo]], None]` | Yes | Receives the current list of ``FunctionInfo`` objects each time availability changes. | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/content/api-reference/sdk-python.mdx` at line 174, The docs show an
incorrect type for the parameter named callback; update the type to the correct
signature Callable[[list[FunctionInfo]], None] (as implemented in iii.py around
line 1018) and fix the doc-generator logic in parse-griffe.mts so it does not
truncate callable signatures—ensure parse-griffe.mts preserves parameterized
Callable types when extracting annotations so the rendered table entry for
callback becomes `Callable[[list[FunctionInfo]], None]`.
Comment on lines
+474
to
+476
| direction: Literal["read", "write"] = Field( | ||
| description="Channel direction (``reader`` or ``writer``)." | ||
| ) |
Contributor
There was a problem hiding this comment.
Fix description mismatch for direction field.
The description says "reader or writer" but the actual Literal type values are "read" and "write".
📝 Proposed fix
direction: Literal["read", "write"] = Field(
- description="Channel direction (``reader`` or ``writer``)."
+ description="Channel direction (``read`` or ``write``)."
)📝 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.
Suggested change
| direction: Literal["read", "write"] = Field( | |
| description="Channel direction (``reader`` or ``writer``)." | |
| ) | |
| direction: Literal["read", "write"] = Field( | |
| description="Channel direction (``read`` or ``write``)." | |
| ) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdk/packages/python/iii/src/iii/iii_types.py` around lines 474 - 476, The
Field description for the direction attribute in iii_types.py is inconsistent
with its type: the Literal is defined as "read" | "write" but the description
says "reader" or "writer"; update the description on the direction Field
(symbol: direction) to accurately state "read or write" (or alternatively change
the Literal values to "reader"/"writer" if those are the intended values) so the
docstring matches the actual type.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improves the auto-generated Python SDK API reference (
sdk-python.mdx) by adding field-level descriptions to all public types and fixing the doc generator to extract them.Before: 34 type fields showed "-" (no description) in the API reference tables.
After: 1 remaining (a method param, not a type field).
Changes
Python SDK docstrings (
iii.py,iii_types.py,iii_constants.py)Attributes:section (Google-style) to 13 Pydantic model docstrings — griffe extracts these for the API referenceregister_function,trigger,create_channel,on_functions_available,register_trigger,register_trigger_type,register_serviceregister_functionexample (removed mixed prose/code)Doc generator (
parse-griffe.mts)extractAttributeDescriptions()— new function that parsesAttributes:sections from class docstrings as fallback when griffe doesn't populate individual field docsregister_workeralias resolution — resolves fromiii.iiisubmodule when the root-level re-export has no metadataextractDocstring()— now strips all Google-style sections (Returns:,Raises:,Note:, etc.) from descriptionsextractExamples()— better cleanup of>>>/...doctest prefixesfrom iii import III, register_workertofrom iii import register_worker, InitOptionsGenerated output (
sdk-python.mdx)register_workerwith description and exampleTest plan
cd sdk/packages/python/iii && uv run pytest tests/ -x— verify no regressionscd sdk/packages/python/iii && uv run griffe dump iii -d google 2>/dev/null > api-docs.json && cd ../../docs && pnpm tsx scripts/generate-api-docs.mts— regenerate and verify outputsdk-python.mdxin docs previewSummary by CodeRabbit
Release Notes
New Features
register_workeras the new primary entry point for Python and Rust SDK initializationInitOptionsconfiguration object for customizable worker setupDocumentation