fix(docs): sanitize emoji shortcodes in generated SDK docs by devin-ai-integration[bot] · Pull Request #631 · OpenRouterTeam/python-sdk

devin-ai-integration · 2026-08-10T20:50:25Z

Summary

The Parameters tables on openrouter.ai/docs/client-sdks/python/** render :heavy_minus_sign: as literal text. Speakeasy emits GitHub-flavored emoji shortcodes; GitHub expands them, Mintlify does not, and the docs site mounts this repo's docs/ tree directly through a sourceRef entry in openrouter-web's projects/docs/docs.json.

Editing the generated MDX alone would not hold, because the next speakeasy run rewrites it. So this PR pairs a one-time pass with a post-generation step:

scripts/sanitize-docs-emoji.sh rewrites docs/**/*.mdx in place:
```
:heavy_check_mark: -> ✅
:heavy_minus_sign: -> ➖
:warning:          -> ⚠️
```
Scoped to docs/ only. README.md, README-PYPI.md, and the workflow YAML keep their shortcodes, which render correctly on GitHub and PyPI.
The script runs in docs-nav.yaml immediately before gen-docs-nav.sh, the existing post-generation docs step.
That workflow's path filter widens from docs/sdks/** to docs/**. The shortcodes live throughout docs/components, docs/operations, and docs/errors as well, and the old filter would skip a generation PR that touched only those trees.

Regeneration PR chore: 🐝 Update SDK - Generate (spec change merged) 1.1.41 #633 landed on main while this PR was open and is exactly that case: its only docs change was docs/components/outputfusionservertoolitem.mdx, so Docs navigation was skipped while PR Validation ran. The widened filter is what closes it.
The one-time pass: 1,429 files, 7,719 shortcodes replaced (rebased onto main on 2026-10-03).
scripts/sanitize-docs-emoji.sh ends with a residual guard: if any standalone :[a-z][a-z0-9_+-]*: token (not preceded or followed by a word character or :) survives the substitution, it prints the file and line and exits non-zero, so a new shortcode Speakeasy starts emitting fails at generation time instead of shipping as literal text. Zero matches remain today, so the guard passes on current output.

Verification

Zero shortcode matches remain under docs/; the six :warning: occurrences in workflow YAML are untouched.
Re-running the script produces no diff.

Rebase (2026-10-03)

Reopened after Pylon #4403 reported the same bug from a customer. The vendor's suggested script only rewrites description fields in OpenAPI files, and the spec has no shortcodes in it, so it doesn't fix this. The shortcodes come from Speakeasy's docs templates.

Rebuilt on current main: same .github and scripts changes, then the one-time pass was re-run fresh instead of replaying the old generated-docs commits.
The residual guard now ignores URN-style colon runs. New OAuth docs on main contain urn:ietf:params:oauth:token-type:jwt, which the old pattern flagged as :params: etc.:
```
- grep -HnE ':[a-z][a-z0-9_+-]*:'
+ grep -HnP '(?<![\w:]):[a-z][a-z0-9_+-]*:(?![\w:])'
```

Link to Devin session: https://openrouter.devinenterprise.com/sessions/1589ee9058c442958d427eac4e989f11
Open in Devin Desktop: https://openrouter.devinenterprise.com/desktop/session/1589ee9058c442958d427eac4e989f11?variant=devin

devin-ai-integration · 2026-08-10T20:50:26Z

Original prompt from jason.schrader

SYSTEM:
=== BEGIN THREAD HISTORY (in #gtm-agents) ===
<most_recent_message>
Jason Schrader (U0BLD9PFY30) [ts=1786394064.313869]: @Devin I found a few spots in our docs where emoji shortcodes are listed in text form and not displayed in tables, e.g. ✔️ renders as :heavy_check_mark: in the table instead of the actual icon. Let's identify the root cause then create a PR to get it all fixed up. From what I see, it's all under a table in the "Parameters" section of the different Client SDK files.
<https://openrouter.ai/docs/client-sdks/typescript/sdks/files/README|openrouter.ai/docs/…/README>
<https://openrouter.ai/docs/client-sdks/python/sdks/benchmarks/README|openrouter.ai/docs/…/README>
<https://openrouter.ai/docs/client-sdks/go/sdks/betaanalytics/README|openrouter.ai/docs/…/README>
</most_recent_message>
=== END THREAD HISTORY ===
Channel ID: C0AD8UNM761
Thread URL: https://openrouter.slack.com/archives/C0AD8UNM761/p1786394064313869?thread_ts=1786394064.313869&cid=C0AD8UNM761

The latest message is the one right above that tagged you. The <most_recent_message> is the message that you should use to guide your goals + task for this session, and you should use the rest of the slack thread as context.
A [ts=...] marker on a Slack message is that message's timestamp. To act on a specific message with the slack tool (e.g. adding an emoji reaction via the reaction command), pass that value as timestamp along with the Channel ID — no extra lookup call is needed.

devin-ai-integration · 2026-08-10T20:50:27Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR that start with 'DevinAI' or '@devin'.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment, CI, and merge conflict monitoring

mintlify · 2026-08-10T21:23:49Z