[pydoclint] tune docstring minimal format errors #52879
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Thomas Desrosiers <[email protected]>
thomasdesr
requested review from
hongpeng-guo,
justinvyu,
matthewdeng,
raulchen and
woshiyyya
as code owners
pcmoritz
approved these changes
May 8, 2025
matthewdeng
approved these changes
May 8, 2025
8 tasks
thomasdesr
added a commit
that referenced
this pull request
May 13, 2025
## Why are these changes needed? Right now the docstring's across Ray's code base are very inconsistent which leads to a number of problems when they are parsed by Sphynx to generate documentation, and are otherwise just harder for folks to read. This adds https://github.com/jsh9/pydoclint to the pre-commit checks to validate that we're meeting a minimum standard that should keep things working (it currently excludes several settings that should probably not be excluded, but they significantly reduce the size of the ratchet file). This PR also includes an allowlist of everything that is currently failing as of commit 25ea331. We'll circle back around over time and fix these, but it should currently operate as a ratchet and only allow the exact set of existing failures to persist. This is likely to generate some logical merge conflicts over the next week or two as PRs are merged that were not based after this was merged, we'll fix them in follow up PRs instead of trying to coordinate a global rollout. ## Related issue number We merged a number of fix PRs already to address basic structural problems in a lot of docstrings: * #52872 * #52873 * #52875 * #52876 * #52877 * #52878 * #52879 * #52880 * #52881 * #52883 + probably more xD <!-- For example: "Closes #1234" --> ## Checks - [x] I've signed off every commit(by using the -s flag, i.e., `git commit -s`) in this PR. - [x] I've run `scripts/format.sh` to lint the changes in this PR. - [ ] I've included any doc changes needed for https://docs.ray.io/en/master/. - [ ] I've added any new APIs to the API Reference. For example, if I added a method in Tune, I've added it in `doc/source/tune/api/` under the corresponding `.rst` file. - [ ] I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/ - Testing Strategy - [ ] Unit tests - [ ] Release tests - [ ] This PR is not tested :( Signed-off-by: Thomas Desrosiers <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Why are these changes needed?
This changes are part a batch effort to rewrite Ray's docstrings to be minimally pydoclint compliant. This PR focuses on making them at least pass basic formatting checks
Related issue number
Checks
git commit -s) in this PR.scripts/format.shto lint the changes in this PR.method in Tune, I've added it in
doc/source/tune/api/under thecorresponding
.rstfile.