164
return type_str
165
166
167
+def _render_rst_role(match: re.Match[str]) -> str:
168
+ """Render an reST role match as inline code, honoring ``~`` short names."""
169
+ target = match.group(1)
170
+ if target.startswith("~"):
171
+ target = target.rsplit(".", 1)[-1]
172
+ return f"`{target}`"
173
+
174
+
175
+def normalize_inline_rst(text: str) -> str:
176
+ """Normalize inline reStructuredText markup to MDX-friendly markdown.
177
+
178
+ Converts reST roles such as ``:class:`Foo` `` into plain inline code and
179
+ reST double-backtick literals (``name``) into single-backtick inline code
180
+ so generated prose renders correctly on the docs site. A ``~`` role prefix
181
+ (``:class:`~mod.Foo` ``) renders as the short target name, matching Sphinx.
182
+ """
183
+ if not text:
184
+ return text
185
+ # ReST roles: :class:`X`, :func:`mod.func`, :meth:`X.y`, :mod:`~pkg.mod`,
186
+ # ... A leading ``~`` requests the short target name, so drop the path.
187
+ normalized = re.sub(r":[a-zA-Z]+:`([^`]+)`", _render_rst_role, text)
188
+ # ReST double-backtick literals: ``name`` -> `name`
189
+ return re.sub(r"``([^`]+)``", r"`\1`", normalized)
190
+
191
+
192
def parse_docstring(docstring: str | None) -> dict[str, Any]:
193
"""Parse docstring into components."""
194
if not docstring:
197
"params": {},
198
"returns": None,
199
"examples": [],
200
+ "raises": [],
201
"deprecated": None,
202
}
203
206
params: dict[str, str] = {}
207
returns = None
208
examples: list[str] = []
209
+ raises: list[dict[str, str]] = []
210
deprecated_lines: list[str] = []
211
212
section = "description"
213
current_param = None
214
+ current_raise: dict[str, str] | None = None
215
example_lines: list[str] = []
216
217
for line in lines:
240
returns = return_match.group(1)
241
continue
242
243
+ # Check for :raises Exc: description (plus common Sphinx synonyms).
244
+ raise_match = re.match(
245
+ r":(?:raises?|except|throws?)\s+([\w.]+):\s*(.*)", stripped
246
+ )
247
+ if raise_match:
248
+ section = "raises"
249
+ current_raise = {
250
+ "exception": raise_match.group(1),
251
+ "description": raise_match.group(2).strip(),
252
+ }
253
+ raises.append(current_raise)
254
+ continue
255
+
256
# Check for Example section
257
if stripped.lower().startswith("example"):
258
section = "examples"
265
params[current_param] += " " + stripped
266
elif section == "returns" and returns and stripped:
267
returns += " " + stripped
268
+ elif section == "raises" and current_raise is not None and stripped:
269
+ current_raise["description"] = (
270
+ current_raise["description"] + " " + stripped
271
+ ).strip()
272
elif section == "examples":
273
example_lines.append(line)
274
elif section == "deprecated" and stripped:
278
examples.append(normalize_example("\n".join(example_lines)))
279
280
return {
236
- "description": " ".join(description_lines).strip(),
237
- "params": params,
238
- "returns": returns,
281
+ "description": normalize_inline_rst(" ".join(description_lines).strip()),
282
+ "params": {name: normalize_inline_rst(desc) for name, desc in params.items()},
283
+ "returns": normalize_inline_rst(returns) if returns else None,
284
"examples": examples,
240
- "deprecated": " ".join(deprecated_lines).strip() if deprecated_lines else None,
285
+ "raises": [
286
+ {
287
+ "exception": entry["exception"],
288
+ "description": normalize_inline_rst(entry["description"]),
289
+ }
290
+ for entry in raises
291
+ ],
292
+ "deprecated": (
293
+ normalize_inline_rst(" ".join(deprecated_lines).strip())
294
+ if deprecated_lines
295
+ else None
296
+ ),
297
}
298
299
337
{
338
"name": name,
339
"type": format_type(member.annotation),
284
- "description": attr_doc.strip() if attr_doc else "",
340
+ "description": (
341
+ normalize_inline_rst(attr_doc.strip()) if attr_doc else ""
342
+ ),
343
}
344
)
345
373
"parameters": params,
374
"return_type": format_type(member.returns),
375
"return_description": method_doc["returns"],
376
+ "raises": method_doc["raises"],
377
"examples": method_doc["examples"],
378
}
379
)
393
if info["description"]
394
else f"{info['name']} class"
395
)
337
- # Normalize reStructuredText ``double backticks`` to single backticks so the
338
- # frontmatter description reads cleanly.
339
- desc = re.sub(r"``([^`]+)``", r"`\1`", desc)
396
if len(desc) > 150:
397
desc = desc[:147] + "..."
398
405
# Class-level deprecation callout (rendered as a fumadocs warning callout).
406
deprecated_note = info.get("deprecated")
407
if deprecated_note:
352
- # Normalize reStructuredText ``double backticks`` to MDX `single` so
353
- # inline code renders correctly.
354
- deprecated_note = re.sub(r"``([^`]+)``", r"`\1`", deprecated_note)
408
lines.append('<Callout type="warn" title="Deprecated">')
409
lines.append(deprecated_note)
410
lines.append("</Callout>")
509
lines.append(f"`{method['return_type']}`")
510
lines.append("")
511
512
+ # Raises
513
+ raises = method.get("raises") or []
514
+ if raises:
515
+ lines.append("**Raises**")
516
+ lines.append("")
517
+ for entry in raises:
518
+ exc_desc = entry["description"]
519
+ if exc_desc:
520
+ lines.append(f"- `{entry['exception']}` — {exc_desc}")
521
+ else:
522
+ lines.append(f"- `{entry['exception']}`")
523
+ lines.append("")
524
+
525
# Examples
526
if method["examples"]:
527
lines.append("**Example**")