docs: ensure that PlotAccessor is included in the API reference#17513
docs: ensure that PlotAccessor is included in the API reference#17513tswast wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
Code Review
This pull request exposes PlotAccessor in the public typing API and updates its references in the documentation templates and docstrings. It also updates the docstring decorator in _tools/docs.py to copy docstrings to property getters. The review feedback recommends making the decorator more robust by separating the docstring assignment of the descriptor from its underlying callable, preventing an AttributeError on the descriptor from skipping the getter's docstring assignment, and extending support to other descriptors like classmethod and cached_property.
| try: | ||
| target_item.__doc__ = source_item.__doc__ | ||
| if isinstance(target_item, property) and target_item.fget: | ||
| try: | ||
| target_item.fget.__doc__ = source_item.__doc__ | ||
| except AttributeError: | ||
| pass | ||
| except AttributeError: | ||
| pass |
There was a problem hiding this comment.
If target_item.__doc__ = source_item.__doc__ raises an AttributeError (which can happen for certain read-only descriptors like classmethod or staticmethod in some Python versions), the execution jumps directly to the outer except AttributeError block, skipping the logic to set the docstring on the underlying getter or function.
To make this decorator more robust and reusable across the codebase, we should:
- Separate the docstring assignment of the descriptor itself from the assignment of the underlying callable.
- Extend support to other common descriptors like
classmethod/staticmethod(which wrap functions in__func__) andcached_property(which wrap functions infunc).
| try: | |
| target_item.__doc__ = source_item.__doc__ | |
| if isinstance(target_item, property) and target_item.fget: | |
| try: | |
| target_item.fget.__doc__ = source_item.__doc__ | |
| except AttributeError: | |
| pass | |
| except AttributeError: | |
| pass | |
| try: | |
| target_item.__doc__ = source_item.__doc__ | |
| except AttributeError: | |
| pass | |
| underlying = None | |
| if isinstance(target_item, property): | |
| underlying = target_item.fget | |
| elif hasattr(target_item, "__func__"): | |
| underlying = target_item.__func__ | |
| elif hasattr(target_item, "func"): | |
| underlying = getattr(target_item, "func", None) | |
| if underlying is not None: | |
| try: | |
| underlying.__doc__ = source_item.__doc__ | |
| except AttributeError: | |
| pass |
Currently, this page is blank.
After this change:
🦕