Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Template function docstrings #9050

Open
vyasr opened this issue Aug 16, 2021 · 4 comments
Open

Template function docstrings #9050

vyasr opened this issue Aug 16, 2021 · 4 comments
Assignees
Labels
doc Documentation proposal Change current process or code Python Affects Python cuDF API.

Comments

@vyasr
Copy link
Contributor

vyasr commented Aug 16, 2021

Many cuDF methods have very similar docstrings, including when the same method is present between different classes, but we currently reproduce most of those docstrings. This increases maintenance burden and the chances of docstrings going out of date. As we work to consolidate more logic a la #9038 we should also consider using more programmatic approaches to share docstrings between related functions, something that pandas does extensively (this has come up in a few of the PRs that already started on the work in #9038).

The main downside to such an approach is that it incurs import time costs that will potentially make import cudf slower. Before diving too deep into trying any such approach, we should verify that the additional import time is not prohibitively slow. I'm reasonably confident that the additional cost will be negligible at the moment, though, because currently importing cupy and numba and setting up the rmm allocator for these account for >90% of the import time. I suspect that unless and until those import times drop, any docstring-related logic that we inject at import time will have a relatively insignificant effect in comparison.

@vyasr vyasr added proposal Change current process or code doc Documentation labels Aug 16, 2021
@vyasr vyasr added this to the CuDF Python Refactoring milestone Aug 16, 2021
@vyasr vyasr self-assigned this Aug 16, 2021
@vyasr
Copy link
Contributor Author

vyasr commented Aug 16, 2021

Note that some utilities for this purpose already exist in docutils.py, my suggestion would be to make more extensive use of them.

@isVoid
Copy link
Contributor

isVoid commented Aug 17, 2021

A potential downside of this is that docs are no longer inline, and may pose difficulty to users who reach the codes by code browser.

@harrism harrism added the Python Affects Python cuDF API. label Aug 17, 2021
@github-actions
Copy link

This issue has been labeled inactive-90d due to no recent activity in the past 90 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed.

@github-actions
Copy link

This issue has been labeled inactive-30d due to no recent activity in the past 30 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed. This issue will be labeled inactive-90d if there is no activity in the next 60 days.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Documentation proposal Change current process or code Python Affects Python cuDF API.
Projects
Status: Todo
Development

No branches or pull requests

4 participants