feat: add Go SDK docs #34
Conversation
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughNew API reference documentation for the Fish Audio Go SDK has been added as an auto-generated file, and the documentation configuration has been updated to include a navigation entry for this reference alongside existing SDK documentation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
api-reference/sdk/go/api-reference.md (1)
118-124: Add language specification to Go code examples.Fenced code blocks containing Go examples are missing the
golanguage identifier. This reduces syntax highlighting quality in markdown viewers and documentation sites.Examples affected:
- Lines 118-124: Transcribe example
- Lines 149-151: GetCredits example
- Lines 165-167: GetPackage example
- Lines 202-216: AudioStream usage example
Update fenced code blocks from:
``` code here ```to:
```go code here ```Also applies to: 149-151, 165-167, 202-216
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
api-reference/sdk/go/api-reference.md
🧰 Additional context used
🪛 LanguageTool
api-reference/sdk/go/api-reference.md
[grammar] ~781-~781: Use a hyphen to join words.
Context: ...error) ``` StreamWebSocket streams text to speech over WebSocket for real-time ...
(QB_NEW_EN_HYPHEN)
[grammar] ~781-~781: Use a hyphen to join words.
Context: ...or) ``` StreamWebSocket streams text to speech over WebSocket for real-time gen...
(QB_NEW_EN_HYPHEN)
[grammar] ~899-~899: Ensure spelling is correct
Context: ...dio-go/blob/main/voices.go#L116-L118>) VoicesService provides voice management operations. ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
api-reference/sdk/go/api-reference.md
118-118: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
148-148: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
164-164: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
201-201: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ 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). (1)
- GitHub Check: Agent
🔇 Additional comments (1)
api-reference/sdk/go/api-reference.md (1)
1-5: Verify auto-generated file quality and source configuration.This file is marked as auto-generated by gomarkdoc and should not be manually edited. However, the output contains rendering issues that should be addressed at the source. Before merging, verify that:
- The gomarkdoc version and configuration are correct
- The generated output is complete and matches the intended SDK structure
- The file should be regenerated if these are configuration issues
| ``` | ||
|
|
||
| <a name="APIError"></a> | ||
| ## type [APIError](<https://github.com/fishaudio/fish-audio-go/blob/main/errors.go#L12-L16>) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's check if the file exists and get its size
wc -l api-reference/sdk/go/api-reference.mdRepository: fishaudio/docs
Length of output: 100
🏁 Script executed:
# Read the file and examine the specific lines mentioned in the review
# Let's start with a few of the cited lines to verify the issue
sed -n '34p;47p;56p;108p;138p;154p' api-reference/sdk/go/api-reference.mdRepository: fishaudio/docs
Length of output: 699
🏁 Script executed:
# Check more of the cited lines to confirm the pattern
sed -n '225p;234p;243p;331p;757p;909p' api-reference/sdk/go/api-reference.mdRepository: fishaudio/docs
Length of output: 705
🏁 Script executed:
# Count how many lines have escaped parentheses in method signatures
rg '\\\\\\(' api-reference/sdk/go/api-reference.md | wc -lRepository: fishaudio/docs
Length of output: 141
🏁 Script executed:
# Count escaped parentheses using a simpler pattern
rg '\\\(' api-reference/sdk/go/api-reference.md | wc -lRepository: fishaudio/docs
Length of output: 60
🏁 Script executed:
# Let's also see the context - check if there are any unescaped parentheses in method signatures
rg '### func \(\*' api-reference/sdk/go/api-reference.md | head -5Repository: fishaudio/docs
Length of output: 40
🏁 Script executed:
# Check the broader context - let's see a complete method signature section
sed -n '45,58p' api-reference/sdk/go/api-reference.mdRepository: fishaudio/docs
Length of output: 401
🌐 Web query:
gomarkdoc escaped parentheses markdown rendering issue
💡 Result:
I don’t have enough detail to diagnose exactly, but common causes and fixes are:
-
Cause: the markdown renderer/writer (e.g., gomarkdown or converters like pandoc) is over‑escaping punctuation when it thinks text could be interpreted as Markdown (links, images, or emphasis). That yields backslashes before parentheses so they render literally. See gomarkdown repo and related escaping behavior in markdown writers. [1][2]
-
Quick checks:
- Show the exact source text and the rendered output (paste both).
- If the parens are inside inline code or a code block, wrap with backticks (code spans) to prevent escaping.
- If the parens are part of a link, ensure proper link syntax: text — otherwise the writer may escape.
- Try rendering with gomarkdown’s parser directly (small reproducer) to confirm whether the library or your toolchain is adding escapes. [1]
-
Workarounds:
- Put the fragment in a code span or fenced code block.
- Use HTML entities or raw HTML when appropriate.
- If converting via another tool (pandoc/hugo/etc.), try using a different markdown dialect or conversion flags — some writers over-escape by default. [2]
-
If you want, paste a minimal example (input → produced markdown → rendered result). I can pinpoint whether it’s gomarkdown itself or another step and suggest a minimal fix or an issue to file against the gomarkdown repo. [1]
Sources:
[1] gomarkdown/markdown repository.
[2] Discussion of over‑escaping behavior in markdown writers (pandoc issues).
Regenerate documentation with proper gomarkdoc configuration to remove unnecessary escaped parentheses in method signatures.
Method signatures contain 38+ instances of incorrectly escaped parentheses (\( and \)) in headers that will render visually as literal backslashes on GitHub and standard markdown viewers. For example, ### func \(\*APIError\) [Error] should render as ### func (*APIError) [Error]. Since this is auto-generated by gomarkdoc, fix the generator configuration to prevent this escaping.
🤖 Prompt for AI Agents
In api-reference/sdk/go/api-reference.md at line 34, the autogenerated headings
contain escaped parentheses (e.g. \(\*APIError\)) because gomarkdoc is
configured to escape parentheses; update the gomarkdoc generation configuration
or template to disable escaping of parentheses in headings (adjust the gomarkdoc
options or template to stop auto-escaping parentheses, e.g. turn off the escape
behavior or remove the escape step), then regenerate the documentation so method
signatures render as (*APIError) instead of \(\*APIError\).
| func (s *TTSService) StreamWebSocket(ctx context.Context, textChan <-chan string, params *StreamParams, opts *WebSocketOptions) (*WebSocketAudioStream, error) | ||
| ``` | ||
|
|
||
| StreamWebSocket streams text to speech over WebSocket for real\-time generation. |
There was a problem hiding this comment.
Use proper hyphenation in description.
Line 781 uses escaped hyphen in "real-time". Should be "real-time" (or use the unescaped hyphen directly).
Current: StreamWebSocket streams text to speech over WebSocket for real\-time generation.
Suggested: StreamWebSocket streams text to speech over WebSocket for real-time generation.
🧰 Tools
🪛 LanguageTool
[grammar] ~781-~781: Use a hyphen to join words.
Context: ...error) ``` StreamWebSocket streams text to speech over WebSocket for real-time ...
(QB_NEW_EN_HYPHEN)
[grammar] ~781-~781: Use a hyphen to join words.
Context: ...or) ``` StreamWebSocket streams text to speech over WebSocket for real-time gen...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In api-reference/sdk/go/api-reference.md around line 781, the description
contains an escaped hyphen "real\-time"; replace the escaped sequence with a
normal hyphen so the sentence reads "StreamWebSocket streams text to speech over
WebSocket for real-time generation." and ensure no unnecessary backslash
remains.
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive API reference documentation for the Fish Audio Go SDK. The documentation is auto-generated by gomarkdoc and provides detailed reference material for all types, functions, and methods in the SDK.
- Added complete API reference documentation for the Go SDK
- Includes detailed descriptions, type definitions, and code examples
- Covers all major services: TTS, ASR, Voices, and Account management
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Example: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
The example code block is missing the language identifier. It should be go instead of just to enable proper syntax highlighting.
| ``` | |
| ```go |
|
|
||
| Example: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
The example code block is missing the language identifier. It should be go instead of just to enable proper syntax highlighting.
| ``` | |
| ```go |
| ``` | ||
| // Stream chunks | ||
| stream, _ := client.TTS.Stream(ctx, params) | ||
| defer stream.Close() | ||
| for stream.Next() { | ||
| chunk := stream.Bytes() | ||
| // process chunk | ||
| } | ||
| if err := stream.Err(); err != nil { | ||
| // handle error | ||
| } | ||
|
|
||
| // Or collect all at once | ||
| stream, _ := client.TTS.Stream(ctx, params) | ||
| audio, err := stream.Collect() | ||
| ``` |
There was a problem hiding this comment.
The example code block is missing the language identifier. It should be go instead of just to enable proper syntax highlighting.
| ``` | ||
| audio, _ := os.ReadFile("audio.mp3") | ||
| result, err := client.ASR.Transcribe(ctx, audio, &fishaudio.TranscribeParams{ | ||
| Language: "en", | ||
| }) | ||
| fmt.Println(result.Text) | ||
| ``` |
There was a problem hiding this comment.
The example code block is missing the language identifier. It should be go instead of just to enable proper syntax highlighting.
…tags for consistency
… Go SDK section in docs.json
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
api-reference/sdk/go/api-reference.mdx (2)
118-124: Add language identifier to example code blocks.This example code block and others (lines 148, 164, 201-216) are missing the
golanguage identifier. Per coding guidelines, all code blocks should include language tags for proper syntax highlighting.🔎 Proposed fix
-``` +```go audio, _ := os.ReadFile("audio.mp3")Apply the same fix to example blocks at lines 148, 164, and 201.
47-47: Escaped parentheses in method signatures persist.Method signatures throughout the file contain escaped parentheses (e.g.,
\(\*APIError\)) that will render as literal backslashes. This affects readability across 38+ instances in the document.
🧹 Nitpick comments (2)
api-reference/sdk/go/api-reference.mdx (2)
67-67: Remove escaped hyphens in descriptions.Multiple descriptions contain unnecessarily escaped hyphens from gomarkdoc generation (e.g.,
speech\-to\-text,real\-time,chunk\-by\-chunk). These should render as normal hyphenated words.Affected lines include: 67, 99, 196, 608, 714, 748, 781.
🔎 Example fix
-ASRResponse contains the result of speech\-to\-text transcription. +ASRResponse contains the result of speech-to-text transcription.
281-281: Remove escaped parentheses around HTTP status codes.Error type descriptions contain escaped parentheses around HTTP status codes (e.g.,
\(401\),\(404\),\(429\),\(5xx\)). These should render as plain parentheses.Affected lines: 281, 556, 597, 622, 679, 839.
🔎 Example fix
-AuthenticationError is raised when authentication fails \(401\). +AuthenticationError is raised when authentication fails (401).
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
api-reference/sdk/go/api-reference.mdxdocs.json
🧰 Additional context used
📓 Path-based instructions (1)
**/*.mdx
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.mdx: Document just enough for user success - not too much, not too little
Prioritize accuracy and usability of information
Make content evergreen when possible
Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
Check existing patterns for consistency
Include title in YAML frontmatter: Clear, descriptive page title
Include description in YAML frontmatter: Concise summary for SEO/navigation
Use second-person voice ("you") in documentation content
Include prerequisites at the start of procedural content
Test all code examples before publishing
Match style and formatting of existing pages
Include both basic and advanced use cases in documentation
Include language tags on all code blocks
Include alt text on all images
Use relative paths for internal links
Never use emojis in professional content
Do not skip frontmatter on any MDX file
Do not use absolute URLs for internal links
Do not include untested code examples
Files:
api-reference/sdk/go/api-reference.mdx
🪛 GitHub Check: Mintlify Validation (hanabiaiinc) - vale-spellcheck
api-reference/sdk/go/api-reference.mdx
[warning] 9-9: api-reference/sdk/go/api-reference.mdx#L9
Did you really mean 'fishaudio'?
[warning] 36-36: api-reference/sdk/go/api-reference.mdx#L36
Did you really mean 'APIError'?
[warning] 67-67: api-reference/sdk/go/api-reference.mdx#L67
Did you really mean 'ASRResponse'?
[warning] 83-83: api-reference/sdk/go/api-reference.mdx#L83
Did you really mean 'ASRSegment'?
[warning] 99-99: api-reference/sdk/go/api-reference.mdx#L99
Did you really mean 'ASRService'?
[warning] 328-328: api-reference/sdk/go/api-reference.mdx#L328
Did you really mean 'apiKey'?
[warning] 714-714: api-reference/sdk/go/api-reference.mdx#L714
Did you really mean 'TTSConfig'?
[warning] 748-748: api-reference/sdk/go/api-reference.mdx#L748
Did you really mean 'TTSService'?
[warning] 783-783: api-reference/sdk/go/api-reference.mdx#L783
Did you really mean 'textChan'?
🪛 LanguageTool
api-reference/sdk/go/api-reference.mdx
[grammar] ~781-~781: Use a hyphen to join words.
Context: ...error) ``` StreamWebSocket streams text to speech over WebSocket for real-time ...
(QB_NEW_EN_HYPHEN)
[grammar] ~781-~781: Use a hyphen to join words.
Context: ...or) ``` StreamWebSocket streams text to speech over WebSocket for real-time gen...
(QB_NEW_EN_HYPHEN)
[grammar] ~899-~899: Ensure spelling is correct
Context: ...dio-go/blob/main/voices.go#L116-L118>) VoicesService provides voice management operations. ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (4)
api-reference/sdk/go/api-reference.mdx (3)
1-5: Frontmatter looks good.The MDX file includes the required
titleanddescriptionin the YAML frontmatter, following the coding guidelines.
9-13: Package import and structure documentation is clear.The import statement and overall document structure follow a logical organization from constants to types to methods.
1083-1083: Auto-generated documentation provides comprehensive API coverage.The gomarkdoc-generated reference covers all public types, methods, and constants from the Go SDK. The "Generated by gomarkdoc" attribution at the end is appropriate.
Consider setting up a CI workflow to regenerate this documentation automatically when the SDK changes, ensuring it stays in sync.
docs.json (1)
203-210: Navigation entry for Go SDK is correct.The new Go SDK navigation group follows the same structure as the existing JavaScript SDK entry, maintaining consistency. The page reference path is accurate, and
golangis a valid Font Awesome brands icon supported in Mintlify.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.