ENG-9533 feat: render concise, readable types in docgen class documentation#6634
ENG-9533 feat: render concise, readable types in docgen class documentation#6634FarhanAliRaza wants to merge 5 commits into
Conversation
Rework reflex-docgen's type/signature rendering so generated class docs read cleanly instead of leaking implementation noise. - Add a public format_type() that strips module qualifiers, preserves type-alias names, and renders unions (Optional[...]), literals, and callables recursively. - Define the ASGI aliases (Scope, Message, Receive, Send, ASGIApp) via TypeAliasType so their short names survive introspection and docs show e.g. ASGIApp rather than a fully expanded MutableMapping/Awaitable blob. - Render method signatures without self/cls, with forward-ref strings kept verbatim (each annotation independently, so one TYPE_CHECKING-only name doesn't poison the rest) and optionality normalized to match format_type. - Clean field/parameter defaults: show function names or empty-collection literals instead of volatile <function ... at 0x...> reprs, and exclude function-valued field defaults from the methods table. - Polish App attribute docstrings with doc links and a fuller api_transformer description.
Merging this PR will not alter performance
Comparing 
Footnotes
|
Greptile SummaryThis PR reworks
Confidence Score: 5/5Safe to merge — all call sites for the ASGI aliases use them purely as annotations, and the docgen changes are isolated to the documentation pipeline with comprehensive test coverage. The ASGI TypeAliasType change touches types that are only used as annotations (never for isinstance or get_args calls at runtime), so the behavioral change is contained to get_type_hints() introspection, which is exactly the intended improvement. The new format_type / _format_signature logic is well-covered by parameterized tests including edge cases (ParamSpec, forward-ref strings, quote-safe module stripping, lambda defaults). The only minor concern is commented-out list items in two docs files. No files require special attention beyond the two docs files (_plugin.py and apiref.py) where rx.Model was left as a comment rather than removed. Important Files Changed
Reviews (3): Last reviewed commit: "Merge branch 'main' into fix-api-refs" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| if param.default is not empty: | ||
| default = _format_default(param.default, is_factory=False) | ||
| text += f" = {default if default is not None else '...'}" |
There was a problem hiding this comment.
= ...
When _format_default returns None for a lambda or unnamed callable default, the signature renders = ... (the Ellipsis literal). This is a reasonable "hidden default" convention used by stub files, but in generated documentation it can be confused with Python's ... stub-body syntax. Consider an explicit placeholder like = <default> or omitting the default entirely so readers understand there is a default without implying the Ellipsis object is the value.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Fold _literal_value, _EMPTY_FACTORY_DISPLAY, _strip_module_qualifiers, and _optional_from_string into their lone call sites. The string-only forward-ref handling now lives directly in _format_annotation, so the qualifier-stripping and Optional[...] rewrite read top-to-bottom in one place instead of hopping through tiny indirections. No behavior change; tests updated to exercise _format_annotation directly.
|
the App, Event, EventHandler, EventSpec, page still has all of the attributes listed as body text in addition to appearing in the table 
The |
The class description was the raw cleandoc'd docstring, so a Google-style Attributes section rendered both as body text and in the fields table, duplicating every attribute on the API reference page. Parse the docstring into griffe sections once and derive the prose description (sans Attributes) and the attribute mapping from the same result. Also drop the deprecated rx.Model from the generated API reference.
|
Fixed. |
2 participants
Rework reflex-docgen's type/signature rendering so generated class docs read cleanly instead of leaking implementation noise.
All Submissions:
Type of change
New Feature Submission:
Changes To Core Features:
Before
After
