docs: add sdk reference pages for node, python, go#54
Conversation
WalkthroughThis change updates documentation configuration and content. The docs navigation switches from navigation.anchors to navigation.tabs, renames entries, restructures CLI pages into a flat list, and introduces a new top-level SDKs tab with grouped language references for Python, Node.js, and Go. New SDK documentation pages are added: an SDKs overview plus language-specific pages and storage API pages for Python, Node.js, and Go. Additionally, the Vale vocabulary adds “Presigned” and “presigned” to accepted terms. Suggested reviewers
Pre-merge checks (3 passed)✅ Passed checks (3 passed)
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 |
davemooreuws
left a comment
davemooreuws
left a comment
There was a problem hiding this comment.
Make sure you use the mintlify features for Fields. https://mintlify.com/docs/components/fields
![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 (17)
docs/.vale/styles/config/vocabularies/Suga/accept.txt (2)
61-66: Remove duplicate entries (stdin/stdout).Duplicates add noise and slow Vale loads slightly. Keep one occurrence each.
stdin stdout stderr - stdout - stdin var
176-186: Deduplicate GitLab/VSCode terms.Only one casing per exact token is needed within the same list section.
GitLab - GitLab Bitbucket - VSCode Visual Studio Code IntelliJdocs/sdk-reference/go/overview.mdx (2)
8-10: Confirm Go import path.“example/suga” looks placeholder. Replace with the actual module path produced by suga generate.
14-24: Either add missing imports or avoid log/fmt in snippets.Current snippet uses log.Fatal and fmt.Println without imports; consider adding them for completeness or removing them for brevity.
// Initialize client -app, err := suga.NewClient() +app, err := suga.NewClient() if err != nil { - log.Fatal(err) + // handle error }docs/sdk-reference/overview.mdx (1)
15-19: Verify icon names exist in your theme.python/node-js/golang icons should match the docs theme icon set.
docs/sdk-reference/go/storage.mdx (1)
166-168: Clarify units for expiry option.Explicitly state time.Duration to avoid ambiguity.
-- `opts` (...PresignUrlOption): Optional `WithPresignUrlExpiry(duration)` - (default: 5 minutes) +- `opts` (...PresignUrlOption): Optional `WithPresignUrlExpiry(time.Duration)` + (default: 5 minutes)docs/sdk-reference/node/storage.mdx (1)
135-143: Use a consistent style for examples (bucket vs suga.image).Earlier sections use a bucket variable; here you use suga.image. Pick one for consistency or briefly explain both patterns.
docs/sdk-reference/python/storage.mdx (7)
13-14: Add trailing colon in Python signatures.Small accuracy fix for function signatures.
-def read(key: str) -> bytes +def read(key: str) -> bytes:
35-37: Add trailing colon in Python signatures.-def write(key: str, data: bytes) -> None +def write(key: str, data: bytes) -> None:
55-56: Add trailing colon in Python signatures.-def delete(key: str) -> None +def delete(key: str) -> None:
73-74: Add trailing colon in Python signatures.-def list(prefix: str = "") -> List[str] +def list(prefix: str = "") -> List[str]:
100-101: Add trailing colon in Python signatures.-def exists(key: str) -> bool +def exists(key: str) -> bool:
123-125: Add trailing colon in Python signatures.-def get_download_url(key: str, options: Optional[PresignUrlOptions] = None) -> str -def get_upload_url(key: str, options: Optional[PresignUrlOptions] = None) -> str +def get_download_url(key: str, options: Optional[PresignUrlOptions] = None) -> str: +def get_upload_url(key: str, options: Optional[PresignUrlOptions] = None) -> str:
135-142: Use one style (bucket vs suga.image) across examples.Align with earlier sections or add a sentence noting both usages.
docs/sdk-reference/node/overview.mdx (1)
11-18: Verify import path for SugaClient.Relative path ./suga/client may differ from generated output/package name. Align with Quickstart/generator output.
docs/sdk-reference/python/overview.mdx (1)
8-10: Confirm Python import path.from suga_gen.client import SugaClient assumes a specific generator layout. Ensure it matches current suga generate output.
docs/docs.json (1)
59-77: Optional: alphabetize language groups (Go, Node.js, Python) for quicker scanning."groups": [ { "group": "Overview", "pages": ["sdk-reference/overview"] }, - { - "group": "Python", - "pages": [ - "sdk-reference/python/overview", - "sdk-reference/python/storage" - ] - }, { "group": "Node.js", "pages": [ "sdk-reference/node/overview", "sdk-reference/node/storage" ] }, { "group": "Go", "pages": [ "sdk-reference/go/overview", "sdk-reference/go/storage" ] }, + { + "group": "Python", + "pages": [ + "sdk-reference/python/overview", + "sdk-reference/python/storage" + ] + } ]
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/docs.json(1 hunks)docs/sdk-reference/go/overview.mdx(1 hunks)docs/sdk-reference/go/storage.mdx(1 hunks)docs/sdk-reference/node/overview.mdx(1 hunks)docs/sdk-reference/node/storage.mdx(1 hunks)docs/sdk-reference/overview.mdx(1 hunks)docs/sdk-reference/python/overview.mdx(1 hunks)docs/sdk-reference/python/storage.mdx(1 hunks)
🔇 Additional comments (9)
docs/sdk-reference/go/overview.mdx (1)
28-32: LGTM — clear nav to Storage.docs/sdk-reference/overview.mdx (1)
10-12: LGTM — concise Getting Started with CLI link.docs/sdk-reference/go/storage.mdx (1)
171-178: Confirm type casing for PresignUrlOption/WithPresignUrlExpiry.Go style typically uses URL; ensure names match the actual API (PresignURLOption/WithPresignURLExpiry vs PresignUrlOption).
docs/sdk-reference/node/storage.mdx (1)
123-125: LGTM — types and defaults are clear.docs/sdk-reference/node/overview.mdx (2)
24-31: LGTM — simple write/read flow.
35-39: Clear Storage link.docs/sdk-reference/python/overview.mdx (1)
25-29: LGTM — Storage card wiring looks good.docs/docs.json (2)
49-80: SDK Reference dropdown looks correct and well-placed.Structure, icon, and grouping align with existing conventions. Nice addition.
55-77: Verified: all SDK Reference slugs resolve to existing MDX files.
raksiv
force-pushed
the
docs-sdk-reference
branch
from
9819ceb to
e780d4d
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/sdk-reference/go/storage.mdx (1)
171-173: Presigned URL functions should be methods on Bucket.Update signatures to include the receiver to match usage like app.Files.GetDownloadURL/UploadURL.
-func GetDownloadURL(key string, opts ...PresignUrlOption) (string, error) -func GetUploadURL(key string, opts ...PresignUrlOption) (string, error) +func (c *Bucket) GetDownloadURL(key string, opts ...PresignUrlOption) (string, error) +func (c *Bucket) GetUploadURL(key string, opts ...PresignUrlOption) (string, error)
🧹 Nitpick comments (2)
docs/sdk-reference/go/storage.mdx (2)
155-163: Handle error in Exists example when reading.Avoid discarding the read error in examples.
if exists { - content, _ := app.Files.Read("config.json") - // Process content + content, err := app.Files.Read("config.json") + if err != nil { + log.Fatal(err) + } + // Process content }
186-192: Note required import for time-based expiry.Readers may miss the time import when copy/pasting.
// Upload URL with custom expiry (1 hour) +// Requires: import "time" uploadURL, err := app.Files.GetUploadURL("uploads/newfile.pdf", suga.WithPresignUrlExpiry(time.Hour))
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/sdk-reference/go/storage.mdx(1 hunks)docs/sdk-reference/node/storage.mdx(1 hunks)docs/sdk-reference/python/storage.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/sdk-reference/node/storage.mdx
- docs/sdk-reference/python/storage.mdx
🔇 Additional comments (1)
docs/sdk-reference/go/storage.mdx (1)
179-181: No doc update needed: identifiers match code
The SDK definesPresignUrlOptionandWithPresignUrlExpiry(notPresignURLOption), so the docs already reflect the actual identifiers.
raksiv
force-pushed
the
docs-sdk-reference
branch
2 times, most recently
from
75328cb to
2b40c7b
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (6)
docs/sdk-reference/node/storage.mdx (3)
152-160: Clarify presigned URL semantics (units, bounds, method, headers).Add notes on:
- Units: seconds (already implied).
- Allowed range (min/max TTL), default (300s), and clock skew caveats.
- Required HTTP method and any headers clients must include (e.g.,
Content-Type,x-amz-*style headers).If headers/method are SDK-returned values, document how to access them.
31-33: Minor: prefer canonical encoding token.Node examples typically use
'utf8'(no hyphen). Current code works but standardizing improves consistency.-console.log(content.toString('utf-8')); +console.log(content.toString('utf8'));
6-7: Consider adding a short “Getting a bucket client” prelude.A 2–3 line snippet showing how
bucketis obtained (import, client init, bucket selection) will reduce confusion for first-time users. Keep it consistent with the package name used elsewhere in the docs.docs/sdk-reference/go/overview.mdx (3)
22-24: Handle errors in examples.Readers will copy this; show error checks for Write/Read.
- app.Files.Write("key", []byte("data")) - content, err := app.Files.Read("key") + if err := app.Files.Write("key", []byte("data")); err != nil { + log.Fatal(err) + } + content, err := app.Files.Read("key") + if err != nil { + log.Fatal(err) + }
21-21: Cross-link suga.yaml reference.Add a link to the config docs so users know where “names from your suga.yaml” come from.
I can add the correct docs path once you confirm where suga.yaml is documented.
28-32: Tighten copy and align terminology.Use “objects” (not “files”) and include “exists” to match the Storage API page.
- Object storage operations - read, write, delete, list files + Object storage operations — read, write, delete, list, exists (objects)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/docs.json(1 hunks)docs/sdk-reference/go/overview.mdx(1 hunks)docs/sdk-reference/go/storage.mdx(1 hunks)docs/sdk-reference/node/overview.mdx(1 hunks)docs/sdk-reference/node/storage.mdx(1 hunks)docs/sdk-reference/overview.mdx(1 hunks)docs/sdk-reference/python/overview.mdx(1 hunks)docs/sdk-reference/python/storage.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- docs/sdk-reference/python/overview.mdx
- docs/sdk-reference/go/storage.mdx
🚧 Files skipped from review as they are similar to previous changes (5)
- docs/.vale/styles/config/vocabularies/Suga/accept.txt
- docs/sdk-reference/node/overview.mdx
- docs/docs.json
- docs/sdk-reference/overview.mdx
- docs/sdk-reference/python/storage.mdx
🔇 Additional comments (2)
docs/sdk-reference/node/storage.mdx (2)
12-14: Confirm Buffer types match the actual Node SDK.Does
readreturnBuffer(vsUint8Array), and doeswriterequireBufferonly (vsstring/Uint8Array/Readable)? Align docs with the real signatures to avoid user friction.Also applies to: 24-26, 49-51
84-92: Remove optional suggestion forprefix
The Node SDK’slistmethod is implemented asasync list(prefix: string)with no default value, soprefixis required and the docs already match the code. To treat it as optional, first update the implementation inclient/node/src/bucket.tsto use a default (e.g.prefix: string = '') and adjust the signature accordingly.Likely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/sdk-reference/overview.mdx (2)
30-35: TS example: clarify async context/top-level await.If users aren’t on ESM or Node >=18 with top-level await, wrap in an async function (see proposed diff above) to avoid confusion.
18-23: Python example: define data for a working copy/paste.Reading the file provides a minimal, executable example (see diff above).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/docs.json(2 hunks)docs/sdk-reference/overview.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/docs.json
🔇 Additional comments (4)
docs/sdk-reference/overview.mdx (4)
1-11: Solid overview and frontmatter.Clear positioning and consistent tone. Nice.
54-58: Icon names are correct. Verified thatnode-jsandgolangexist in the docs’ icon list; no changes needed.
62-62: Link to/cli/generateis valid. The page exists atdocs/cli/generate.mdx.
15-16: Verifysuga generateflags
Docs use--python,--ts, and--goconsistently—please confirm these match the actual CLI (e.g. viasuga generate --helpor inspecting the CLI code) and update docs/sdk-reference/overview.mdx (lines 15–16, 27–28, 39–40) if they differ.
raksiv
force-pushed
the
docs-sdk-reference
branch
3 times, most recently
from
a321792 to
d61c58a
Compare
|
Changed to tabs and restructured the pages. |
davemooreuws
force-pushed
the
docs-sdk-reference
branch
2 times, most recently
from
507d12a to
81a0333
Compare
davemooreuws
force-pushed
the
docs-sdk-reference
branch
from
81a0333 to
0394d6d
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
docs/sdks/python.mdx (3)
2-2: Prefer a more specific page title for SEO/clarity.Recommend “Python SDK Overview” so it’s unambiguous in tab/search results.
-title: "Overview" +title: "Python SDK Overview"
23-30: Add a brief auth/import-path note to reduce first-run friction.Link to the access token doc and show how to put suga_gen on PYTHONPATH so
from suga_gen.client import SugaClientworks out of the box.For all available options, see the [`suga generate`](/cli/generate) command documentation. ## Import ```python from suga_gen.client import SugaClient
+> Note
+> - Ensure you’ve authenticated first; see Access Token.
+> - If you import from a generated folder, add it to your PYTHONPATH (example):
+>
+>bash +> export PYTHONPATH="$PWD/suga_gen:$PYTHONPATH" +>--- `44-48`: **Grid has a single card; set cols=1 for nicer layout.** ```diff -<CardGroup cols={2}> +<CardGroup cols={1}> <Card title="Storage" icon="database" href="/sdks/python/storage"> Object storage operations - read, write, delete, list files </Card> </CardGroup>docs/docs.json (1)
65-67: Minor naming nit: avoid repeating “SDKs” in tab + group.Consider “Overview” for the group label.
- "group": "SDKs", + "group": "Overview",
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/docs.json(2 hunks)docs/sdks.mdx(1 hunks)docs/sdks/go.mdx(1 hunks)docs/sdks/go/storage.mdx(1 hunks)docs/sdks/node.mdx(1 hunks)docs/sdks/node/storage.mdx(1 hunks)docs/sdks/python.mdx(1 hunks)docs/sdks/python/storage.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (6)
- docs/sdks/node/storage.mdx
- docs/sdks.mdx
- docs/sdks/go.mdx
- docs/sdks/node.mdx
- docs/sdks/go/storage.mdx
- docs/sdks/python/storage.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/.vale/styles/config/vocabularies/Suga/accept.txt
🔇 Additional comments (3)
docs/sdks/python.mdx (1)
31-40: Nice concise example.Reads/writes are clear and map well to the generated client surface.
docs/docs.json (2)
61-89: Structure looks good.Tabs + grouped language references read cleanly and match the new SDK pages.
40-59: All CLI pages verified – no missing .md/.mdx files detected.
| "group": "Python", | ||
| "icon": "python", | ||
| "pages": ["sdks/python", "sdks/python/storage"] | ||
| }, | ||
| { | ||
| "group": "Node.js", | ||
| "icon": "node-js", | ||
| "pages": ["sdks/node", "sdks/node/storage"] | ||
| }, | ||
| { | ||
| "group": "Go", | ||
| "icon": "golang", | ||
| "pages": ["sdks/go", "sdks/go/storage"] | ||
| } |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Double-check icon keys for language groups.
Mintlify icon keys can be strict; please verify “node-js” and “golang” are valid.
🌐 Web query:
What are the valid icon names for Mintlify docs.json groups/tabs, specifically for Python, Node.js, and Go?
💡 Result:
Short answer
- Mintlify accepts any named Font Awesome or Lucide icon (or a URL / local SVG). [1][2]
Recommended icon names
- Python: "python" (Font Awesome brand). [3]
- Node.js: "node" or "node-js" (Font Awesome brands; both are available). [4][5]
- Go: there is no official Go / golang brand icon in Font Awesome; use a custom SVG or an external URL (Mintlify supports SVG/URL icons). [1][2]
Sources
- Mintlify — Icons / docs.json icon options. [Mintlify docs]. [1]
- Mintlify — Navigation (groups/tabs accept icon names from Font Awesome or Lucide). [1]
- Font Awesome — python brand icon. [3]
- Font Awesome — node brand icon. [4]
- Font Awesome — node-js brand icon. [5]
Use a custom SVG or URL for the Go icon. Font Awesome provides “python” and “node-js” out of the box, but there’s no official “golang” icon—update the Go group in docs/docs.json to reference a custom SVG or external URL.
🤖 Prompt for AI Agents
In docs/docs.json around lines 72 to 85, the "Go" group uses an invalid Font
Awesome icon name "golang"; replace that value with a reference to a custom SVG
or external URL (for example a relative path under the docs static assets like
"static/icons/go.svg" or a full CDN URL), ensure the referenced SVG file exists
in the repo (add it to docs/static/icons/) and update any build/config that
copies static docs assets so the icon will be served correctly.
|
🎉 This PR is included in version 0.0.6 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
7 participants
Add reference docs for param info and examples on how to use the client SDKs
Resolves NIT-210