Hide __init__ signature from autogenerated client classes, expand doctest coverage#266
Hide __init__ signature from autogenerated client classes, expand doctest coverage#266
Conversation
WalkthroughThis pull request updates several driver documentation files by modifying the autoclass directives to include parentheses, ensuring that classes are treated as instantiable entities in the rendered output. In addition, new configuration sections and doctest examples are added to the SDWire and UStreamer documentation along with accompanying YAML configuration files. A new class method is also introduced in the exporter configuration module to load and validate YAML configuration from a given file path. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant ConfigLoader as ExporterConfigV1Alpha1DriverInstance
participant FileSystem
participant YAML
Client->>ConfigLoader: from_path("config.yaml")
ConfigLoader->>FileSystem: Open "config.yaml"
FileSystem-->>ConfigLoader: File contents
ConfigLoader->>YAML: yaml.safe_load(contents)
YAML-->>ConfigLoader: Parsed data
ConfigLoader->>ConfigLoader: model_validate(data)
ConfigLoader-->>Client: Return Config Instance (or raise error)
Possibly related PRs
Suggested reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/source/api-reference/drivers/ustreamer.yaml (1)
8-8: Fix typo in comment.There's a typo in the comment for the contrast argument.
Apply this diff to fix the typo:
- contrast: default # --contract=default + contrast: default # --contrast=default
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
docs/source/api-reference/drivers/can.md(1 hunks)docs/source/api-reference/drivers/pyserial.md(1 hunks)docs/source/api-reference/drivers/sdwire.md(1 hunks)docs/source/api-reference/drivers/sdwire.yaml(1 hunks)docs/source/api-reference/drivers/ustreamer.md(1 hunks)docs/source/api-reference/drivers/ustreamer.yaml(1 hunks)docs/source/api-reference/drivers/yepkit.md(1 hunks)packages/jumpstarter/jumpstarter/config/exporter.py(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- docs/source/api-reference/drivers/can.md
- docs/source/api-reference/drivers/pyserial.md
- docs/source/api-reference/drivers/yepkit.md
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: e2e
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-devspace .devfile/Containerfile.client)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-dev .devfile/Containerfile)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter Dockerfile)
🔇 Additional comments (6)
docs/source/api-reference/drivers/sdwire.yaml (1)
1-8: LGTM!The configuration is well-structured with clear comments explaining the optional parameters.
docs/source/api-reference/drivers/ustreamer.md (1)
7-24: LGTM!The changes effectively achieve the PR objectives:
- Added driver configuration section with clear YAML example
- Added hidden doctest example for configuration loading
- Updated autoclass directive to hide init signature
docs/source/api-reference/drivers/sdwire.md (4)
7-8: New "Driver Configuration" Section Added.This heading clearly delineates the configuration instructions, improving the overall documentation structure and aiding users in quickly finding YAML configuration details.
9-11: YAML Configuration Snippet Integration.Using the literalinclude directive for "sdwire.yaml" is an effective way to embed configuration details directly into the docs. Please verify that the relative file path is correct during the docs build process.
13-20: Enhanced Doctest Example for Error Handling.The added doctest block now demonstrates the behavior when the YAML file is missing, aligning well with expanding doctest coverage. Ensure that the file path used in the test ("source/api-reference/drivers/sdwire.yaml") is accurate within the test environment.
28-29: Autoclass Directive Update to Hide init Signature.Appending parentheses in the autoclass directive for StorageMuxClient effectively hides the init signature in the autogenerated output, fulfilling one of the key PR objectives. This change is consistent with similar updates in the codebase.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/source/api-reference/drivers/ustreamer.md (1)
13-20: Doctest example enriches configuration instantiation coverage.
The doctest demonstrates how to load and instantiate configuration via ExporterConfigV1Alpha1DriverInstance and intentionally expects an io.UnsupportedOperation error. To further improve clarity for end users, consider adding an inline comment explaining why this error is expected (e.g., due to limitations with file descriptor handling in this context).docs/source/api-reference/drivers/sdwire.md (1)
13-20: Doctest example for configuration instantiation is a useful addition.
The doctest shows the expected behavior by triggering a FileNotFoundError when the SDWire device is missing. To improve user understanding, consider adding a brief explanation (perhaps as a comment within the code block) describing why this error is expected.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
docs/source/api-reference/drivers/can.md(1 hunks)docs/source/api-reference/drivers/pyserial.md(1 hunks)docs/source/api-reference/drivers/sdwire.md(1 hunks)docs/source/api-reference/drivers/sdwire.yaml(1 hunks)docs/source/api-reference/drivers/ustreamer.md(1 hunks)docs/source/api-reference/drivers/ustreamer.yaml(1 hunks)docs/source/api-reference/drivers/yepkit.md(1 hunks)packages/jumpstarter/jumpstarter/config/exporter.py(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (6)
- packages/jumpstarter/jumpstarter/config/exporter.py
- docs/source/api-reference/drivers/yepkit.md
- docs/source/api-reference/drivers/pyserial.md
- docs/source/api-reference/drivers/can.md
- docs/source/api-reference/drivers/sdwire.yaml
- docs/source/api-reference/drivers/ustreamer.yaml
⏰ Context from checks skipped due to timeout of 90000ms (7)
- GitHub Check: pytest-matrix (3.13)
- GitHub Check: pytest-matrix (3.12)
- GitHub Check: e2e
- GitHub Check: pytest-matrix (3.11)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-devspace .devfile/Containerfile.client)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-dev .devfile/Containerfile)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter Dockerfile)
🔇 Additional comments (6)
docs/source/api-reference/drivers/ustreamer.md (3)
7-8: New "Driver configuration" section added.
The addition of the "Driver configuration" section clearly separates configuration-related details from other content, which enhances the overall documentation clarity.
9-11: Literalinclude block for YAML configuration is well-formed.
The code block using the literalinclude directive correctly points to "ustreamer.yaml" and specifies YAML as the language. Make sure the referenced file path remains consistent with the documentation build system.
22-27: Autoclass directive updated to hide the init signature.
Changing the directive toUStreamerClient()meets the design goal by ensuring that the autogenerated client class hides the init signature, thereby presenting a cleaner public API.docs/source/api-reference/drivers/sdwire.md (3)
7-8: "Driver Configuration" section enhances documentation clarity.
This new section clearly indicates where users can find configuration details specific to the SDWire driver, aligning the documentation with the updated configuration structure.
9-11: Literalinclude directive for sdwire.yaml is correctly configured.
The inclusion of the YAML configuration file via literalinclude is correctly set up with the language specified as YAML. Verify that the file path is correct relative to the documentation directory.
22-31: Autoclass directive for StorageMuxClient updated as intended.
Modifying the autoclass directive to include parentheses (i.e.StorageMuxClient()) successfully hides the init signature from the autogenerated documentation, thereby streamlining the presented API.
2 participants
Summary by CodeRabbit