-
Notifications
You must be signed in to change notification settings - Fork 532
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
[REVIEW] Improve Python Docs with Default Role #3445
[REVIEW] Improve Python Docs with Default Role #3445
Conversation
Note: This PR doesn't significantly change the existing functionality. Only single backticks will be changed to better align with how developers have been using them. Double backticks for literal code are unchanged, and the new |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm, very nice imporovement. @mdemoret-nv do you think it'd be a good idea to open an issue about adopting the new py feature uniformly around?
We can. It would be a very tedious process for one person but would have a nice effect on the docs. Could be a team effort. @JohnZed what do you think? |
Agreed on opening an issue and adding to the Technical Debt project. We can also move over time as people update various submodules, they can update docstrings accordingly. |
@gpucibot merge |
Done: #3451 |
This PR sets the default type of "interpolated text" in sphinx to
:py:obj:
. This is very useful for us since we frequently use a single backtick in our python documentation to refer to another python object.Currently, the docstring:
Would generate (italicized, variable spaced):
This PR changes it to (bold, mono spaced):
The added benefit here is if the interpolated text is found in the index, it will link to that section. So in the above example, clicking on
cuml.datasets.make_blobs
will take you to the function documentation.Finally, this PR adds a new type of interpolated text role:
:py:
. This should be used for inline python code. For example, the following code:will generate:
I also looked for a few examples to replace to help seed usage of these new options. Updating every location would be very time consuming and is best done over time.