docs: restructured sync vs async sdk and resources, added support for more type references #679
Conversation
…c and async documentation into separate pages
jrvb-rl
left a comment
jrvb-rl
left a comment
There was a problem hiding this comment.
This looks great! I like the organization and overall structure; very easy to find the main parts of the SDK.
| ~~~~~~~~~~~~~~~~~~~~ | ||
| -------------------- | ||
|
|
||
| These TypeDicts define options for streaming, timeouts, polling, and other request configuration. |
There was a problem hiding this comment.
From my read, these are more like low-level plumbing options? Maybe put these at the bottom instead? Or are these options that can be added to any request? If so, let's make that more clear in the description.
|
|
||
| These are the primary TypedDict classes used in SDK methods, combining multiple | ||
| parameter types and options. | ||
| This page documents all TypeDict parameter types used throughout the SDK. |
There was a problem hiding this comment.
Probably good to provide a bit more context. Maybe something like this?
"The Runloop Python SDK uses TypeDict objects for configuration parameters to the various API calls. This page documents the parameter objects used throughout the SDK."
|
|
||
| Devbox Parameters | ||
| ~~~~~~~~~~~~~~~~~ | ||
| ----------------- |
There was a problem hiding this comment.
Since Devbox is also an object type, the header "Devbox Parameters" sounds like these would be constructor params. Maybe better as "Devbox Method Parameters" or some such?
|
|
||
| These TypeDicts define parameters for devbox creation, execution, file operations, network tunnels, and snapshots. | ||
|
|
||
| Creation Parameters |
There was a problem hiding this comment.
Why the distinction between CreateParams and ExtraCreateParams? And why the overlap? I'm guessing as a user I can just use any of the params from either of these in the runloop.devbox.create() call, in which case splitting them here is a bit odd. If we need to do this due to some wonky implementation detail, let's add a bit of explanation at least as to why, and show how these are used?
Oh - and it looks like the only diff in the list of params is that the 'Extra' version has fewer? (it's missing the blueprint and snapshot params)
We now have 3 top level pages within the docs: Synchronous SDK, Asynchronous SDK and Type Reference. Within each of the SDK pages, we have the core resource manager classes, and subpages for each of the resource classes. The type reference is also organized by type of parameter (core request options vs devbox params vs blueprint params, etc.)