fix(docs): escape curly braces and always fence examples for MDX#585
fix(docs): escape curly braces and always fence examples for MDX#585xke wants to merge 1 commit into
Conversation
The autogenerated MDX docs in docs-official have been failing CI
with acorn parse errors because the generator emits unescaped
`{...}` in body prose (e.g. RST literal blocks, dict literals
in docstring descriptions) and unfenced Python in Examples
sections that don't use the doctest `>>>` prefix.
Changes:
- Lift `escape_curly_braces` to module scope so all three writers
can use it.
- Add `render_examples` helper that always wraps each example in
a python code fence and strips doctest prefixes line-by-line.
- Apply `escape_curly_braces` to every description, param desc,
raise desc, return desc, and note text in write_function,
write_class, and write_module.
- Replace the conditional ``` opener (only fenced when example
starts with `>>>`) with unconditional fencing.
This eliminates the recurring CI failures on docs-official PRs
generated by the Publish Docs workflow.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #585 +/- ##
=======================================
Coverage 83.27% 83.27%
=======================================
Files 125 125
Lines 10617 10617
=======================================
Hits 8841 8841
Misses 1776 1776 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![baz-reviewer[bot]](https://avatars.githubusercontent.com/in/933528?s=60&v=4){kind=small}
| parts.append("```python") | ||
| parts.append("\n".join(stripped).rstrip()) | ||
| parts.append("```\n") |
There was a problem hiding this comment.
render_examples() now wraps every parsed example in an outer ```python fence even when the example text already has Markdown/prose, so nested fences get stored in examples[].code and the MDX render breaks. Can we detect/prevent pre-fenced blocks or split prose vs code before adding the wrapper fence?
Finding type: Breaking Changes | Severity: 🟠 Medium
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
scripts/create_docs.py around lines 524-542 inside `render_examples(parts, examples)`,
fix the example formatting to avoid nesting Markdown fences. Right now the function
always appends an outer ```python fence and then dumps the entire `ex['code']`, which
can already contain triple-backtick blocks plus explanatory prose, causing broken MDX
rendering. Refactor `render_examples` to detect when `code` already includes
triple-backtick fences (and in that case append the content without wrapping again, or
parse/split prose from fenced code before fencing); keep the doctest `>>>` / `...`
stripping behavior only for lines that are actual doctest prompts. Ensure the output
matches the previous behavior of only adding fences when the example truly contains
doctest snippets rather than pre-fenced Numpydoc sections.
| parts.append("**Arguments**\n") | ||
| for p in md.get("params", []): |
There was a problem hiding this comment.
The params rendering block is duplicated in write_class and write_function, repeating the same doc.get('params') iteration, escaping, and bullet markup—should we extract it into a shared helper like append_param_list(parts, params) so future formatting/escaping changes only touch one place?
Finding type: Code Dedup and Conventions | Severity: 🟢 Low
Want Baz to fix this for you? Activate Fixer
1 participant
User description
Summary
The
Publish Docsworkflow has been generating MDX files that fail Mintlify's MDX parser on the consuming side (rungalileo/docs-official). Recent docs-official PRs (#902, #906) both hit acorn parse errors that required manual MDX patching. This fix addresses the root cause increate_docs.py.Bugs fixed
Unescaped
{...}in body prose.description,returns,raises, andnotestext was emitted raw. Any docstring that included a Python dict literal, f-string format spec, or RST literal block with{...}would produce MDX that acorn tried to parse as a JSX expression and rejected. Example failure:experiment.mdx:498:38parsing{agg.avg:.3f}in a::literal block.Examples only fenced when prefixed with
>>>. Plain-Python example sections (no doctest prefix) were emitted unfenced, so any{inside them tripped the same JSX parser. Example failure:dataset.mdx:21:17parsing{"input": ...}.escape_curly_braceswas scoped insidewrite_function's params loop and applied nowhere else — includingwrite_classparams, which had no escaping at all.Changes
escape_curly_bracesto module scope so all three writers (write_function,write_class,write_module) can use it.render_exampleshelper that wraps each example in a python fence unconditionally and strips>>>/...doctest prefixes line-by-line.escape_curly_bracesto every description, param desc, raise desc, return desc, and note text across the three writers.render_examples.Net: +56 / -65 lines (consolidation via helpers).
Test plan
python3 -c "import ast; ast.parse(open('scripts/create_docs.py').read())"— file parsesPublish Docsworkflow manually after merge and verify the generated PR againstdocs-officialpasses CI without manual MDX patchesOut of scope
This fix prevents MDX parse errors but does not convert RST
::literal blocks into proper fenced code blocks — those will still render with literal::and an indented but unhighlighted block. That's a bigger refactor (would require walking the description string with an RST-aware parser) and worth filing separately if rendering quality matters.🤖 Generated with Claude Code
Generated description
Below is a concise technical summary of the changes proposed in this PR:
Update
create_docs.pyto escape curly braces in descriptions, params, raises, returns, and notes so MDX consumers no longer misinterpret prose as JSX, and consolidate the helper for these writers. Ensure every documented example runs through the new fencedrender_exampleshelper that strips doctest prefixes before emitting python code blocks.write_function,write_class, andwrite_modulewith the module-levelescape_curly_braceshelper so descriptions, params, raises, returns, and notes never emit raw{...}sequences.Modified files (1)
Latest Contributors(2)
render_exampleshelper that strips doctest>>>/...prefixes and emits a consistent python code block every time a function, class, or module declares examples.Modified files (1)
Latest Contributors(2)