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

[REVIEW] Improve Python Docs with Default Role #3445

Merged

Conversation

mdemoret-nv
Copy link
Contributor

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:

`cuml.datasets.make_blobs`

Would generate (italicized, variable spaced):
image

This PR changes it to (bold, mono spaced):
image

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:

 * `cuml.cuml.datasets.make_blobs` for references do objects (functions, classes, modules, etc.)
 * :py:`import cupy as cp` for inline python code
 * ``import cupy as cp`` for literal code

will generate:
image

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.

@mdemoret-nv mdemoret-nv added 3 - Ready for Review Ready for review by team doc Documentation improvement Improvement / enhancement to an existing function non-breaking Non-breaking change labels Feb 1, 2021
@mdemoret-nv mdemoret-nv requested a review from a team as a code owner February 1, 2021 23:36
@github-actions github-actions bot added the Cython / Python Cython or Python issue label Feb 1, 2021
@mdemoret-nv
Copy link
Contributor Author

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 :py: inline code is new.

@dantegd dantegd removed the improvement Improvement / enhancement to an existing function label Feb 2, 2021
Copy link
Member

@dantegd dantegd left a 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?

@mdemoret-nv
Copy link
Contributor Author

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?

@JohnZed
Copy link
Contributor

JohnZed commented Feb 2, 2021

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.
BTW, this change looks great

@JohnZed
Copy link
Contributor

JohnZed commented Feb 2, 2021

@gpucibot merge

@mdemoret-nv
Copy link
Contributor Author

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.
BTW, this change looks great

Done: #3451

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
3 - Ready for Review Ready for review by team Cython / Python Cython or Python issue doc Documentation non-breaking Non-breaking change
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants