docs: pipeline-generated pages (?, Languages, Voice) - #446
github-actions[bot] wants to merge 1 commit into
Conversation
Generated 3 pages for: Languages, Voice, unknown - docs/voice/translate-a-pre-recorded-audio-file.mdx: No guide (tutorial or how-to) covers the 'Translate Audio Files' endpoints - docs/languages/query-supported-languages-for-a-resource.mdx: No guide (tutorial or how-to) covers the 'Languages' endpoints - docs/learning-how-tos/cookbook/google-sheets: docs/learning-how-tos/cookbook/google-sheets has under 100 words
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| print(f"Source languages: {len(source_languages)}") | ||
| print(f"Target languages: {len(target_languages)}") | ||
|
|
There was a problem hiding this comment.
Step 4 function does not handle missing lang_by_code keys
The example calls lang_by_code.get('en') and lang_by_code.get('de'), which can return None. Passing None to feature_supported() will raise an AttributeError on .get('features', {}). The guide doesn't warn about this or show defensive handling, so a reader copy-pasting into production code could hit a silent bug.
Suggested fix: Add a guard before the call, e.g. if source is None or target is None: raise ValueError(...), or add a note that the caller must validate the codes exist in lang_by_code before calling the function.
| url, | ||
| headers={"Authorization": f"DeepL-Auth-Key {API_KEY}"} | ||
| ) | ||
| with urllib.request.urlopen(req) as response: |
There was a problem hiding this comment.
Step 4 comment logic for 'all other features' is stated as a rule but may be inaccurate
The comment 'All other features (glossary, tag_handling) require both languages to support them' asserts a product rule inline. If this rule is wrong or changes, the code silently misbehaves. The guide says to see the API reference for full details, but the comment presents it as definitive. Either remove the assertion and defer to the reference, or cite the reference inline.
Suggested fix: Change the comment to: '# For glossary and tag_handling, check both languages — see the API reference for the exact rules per resource.' and remove the implied guarantee that this covers all cases.
| return source_ok and target_ok | ||
|
|
||
|
|
||
| # Example: check if formality is supported for English → German |
There was a problem hiding this comment.
Step 5 lacks an example response
All other steps that make an API call (Steps 2, 3) show a response. Step 5 adds the include=beta parameter but shows only the request. Per CLAUDE.md, API requests should be paired with sample responses.
Suggested fix: Add a truncated example JSON response showing at least one language entry with "status": "beta" and one feature with "status": "beta" to illustrate what the beta output looks like.
| @@ -0,0 +1,173 @@ | |||
| --- | |||
| title: "Query supported languages for a resource" | |||
There was a problem hiding this comment.
Frontmatter description could be more specific about the outcome
The description 'fetch which languages and features a specific DeepL API resource supports, then filter and use that data in your integration' is accurate but somewhat generic on the second half. It would be clearer if it named the concrete outcomes (source/target separation, feature detection).
| title: "Query supported languages for a resource" | |
| title: "Query supported languages for a resource" | |
| description: "Use GET /v3/languages to fetch supported languages for a DeepL resource, then separate source and target languages and check feature support before making translation requests." |
| "tag_handling": { "status": "stable" } | ||
| } | ||
| } | ||
| ] |
There was a problem hiding this comment.
Step 3 output does not show example console output
The Python snippet prints to stdout but no expected output is shown. Other steps show responses; consistency suggests showing the expected print output here (e.g. 'Source languages: 31 / Target languages: 33') so readers can verify they're on track.
Suggested fix: Add a comment block or a separate code block after the snippet showing expected output, e.g.: # Source languages: 31\n# Target languages: 33
|
|
||
| <Info> | ||
| The `/v3/languages` endpoint replaces the deprecated `/v2/languages` endpoint. If you're currently using `/v2/languages`, see the [migration guide](/docs/languages/migrating-from-v2-languages) for differences and code examples. | ||
| </Info> |
There was a problem hiding this comment.
Info box references a migration guide that may not exist
The <Info> box links to /docs/languages/migrating-from-v2-languages. If this page does not exist, the link is broken. The 'Next steps' section also links to it. Verify both links resolve.
| </Info> | |
| </Info> | |
| > **Note:** A migration guide for `/v2/languages` to `/v3/languages` is forthcoming. In the meantime, refer to the API changelog for differences. |
|
|
||
| A successful response returns `201` with a `job_id`, an `upload_url`, and a `signature`: | ||
|
|
||
| ```json |
There was a problem hiding this comment.
Upload URL used verbatim in Step 2 curl example
The curl command in Step 2 hardcodes the full upload_url value from the Step 1 response example. This is fine for illustration, but the text before it says 'PUT your audio file directly to the upload_url' without making it explicit that the reader should substitute the actual URL returned in their response, not copy this literal URL. A brief note or variable placeholder would prevent copy-paste confusion.
| ```json | |
| Replace `$UPLOAD_URL` with the `upload_url` from the step 1 response. | |
| ```bash | |
| UPLOAD_URL="https://assets.deepl.com/collections/a74d88fb-ed2a-4943-a664-a4512398b994/assets/b1c2d3e4-f5a6-7890-abcd-ef1234567890" | |
| SKIP |
|
|
||
| ```json | ||
| { | ||
| "job_id": "a74d88fb-ed2a-4943-a664-a4512398b994", |
There was a problem hiding this comment.
Poll interval recommendation has no upper bound rationale
The guide recommends polling every 5-10 seconds but gives no guidance on when to stop if the job appears stuck or on maximum expected processing time. Developers building production integrations may implement infinite polling loops. A brief note on a reasonable timeout or maximum wait time would help.
Suggested fix: Add a sentence after 'Poll every 5-10 seconds.' such as: 'Processing time varies with file length; a 1-hour recording may take several minutes. If the job has not completed after 30 minutes, treat it as failed and file a support request.'
|
|
||
| ```json | ||
| { | ||
| "results": [ |
There was a problem hiding this comment.
Download expiry window (1 hour) and upload window (5 minutes) sourcing not cross-referenced to reference docs
The 1-hour download expiry and 5-minute upload window are stated as facts in the guide, but there is no cross-reference to a reference page or requirements page that confirms these limits. If the limits change, this guide may go stale. The 'Voice API Requirements' link in Handling Failures covers rate/size limits but may not cover these time windows.
Suggested fix: Add a parenthetical link after each time limit pointing to the canonical source, e.g. 'within 1 hour (see Voice API Requirements)' — or confirm the requirements page covers these windows and relies on it as the single source of truth.
|
|
||
| Results are returned in the same order as the `targets` array from your create request. | ||
|
|
||
| Poll every 5-10 seconds. When a target's status changes to `complete`, its result object includes a `download_url` and a `signature`: |
There was a problem hiding this comment.
Step 4 audio file extension guidance is informal and incomplete
The note 'use a file extension that matches the output format (.wav for PCM, .mp3 for MPEG, and so on)' is informal guidance without a pointer to a format reference. 'And so on' leaves developers to guess for other formats like SRT. A link to the supported output formats list would make this actionable.
Suggested fix: Replace 'and so on' with a link: 'For a full list of output types and their conventional extensions, see Supported Output Formats.'
|
Closing as superseded by #447. This PR and #447 address the same two gaps ( Root cause: a gap stayed open until its PR merged, but the pipeline re-derived gaps from scratch each run, so every spec change reshipped the same pages. Eight of these were open. Fixed in #449, which makes the pipeline check open PRs before drafting and before shipping. |
This branch was successfully deployed
1 participant
Summary
Generated documentation pages from the agentic docs pipeline (run
20260922-100739).Families: Languages, Voice, unknown
Model: claude-sonnet-4-6
Pages added/updated
docs/voice/translate-a-pre-recorded-audio-file.mdx— missing_group_coveragedocs/languages/query-supported-languages-for-a-resource.mdx— missing_group_coveragedocs/learning-how-tos/cookbook/google-sheets— expanded thin pageQuality checks
How to review
mint devto preview locallyGenerated by the agentic docs pipeline (
pipeline/generate.py)