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

STY: Use ruff to format docstrings #56863

Merged
merged 24 commits into from
Feb 8, 2024
Merged

Conversation

mroeschke
Copy link
Member

@mroeschke mroeschke commented Jan 13, 2024

closes #56804

@mroeschke mroeschke added Docs Code Style Code style, linting, code_checks labels Jan 13, 2024
@tqa236 tqa236 mentioned this pull request Jan 14, 2024
5 tasks
Comment on lines 72 to 74
MSG='Partially validate docstrings (EX03)' ; echo $MSG
$BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX03 --ignore_functions \
pandas.Series.plot.line \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are you sure this can be removed? ruff only works statically, so only checks generated docstrings - any docstring with a substitution won't be checked. that's what validate_docstrings.py does

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah good point. Yeah none of the dynamic docstrings were able to get formatted so I'll revert this

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one more reason to get rid of dynamic docstrings 😉

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Big +1 to remove them!

>>> s = pd.Series({{'Corn Flakes': 100.0, 'Almond Delight': 110.0,
... 'Cinnamon Toast Crunch': 120.0, 'Cocoa Puff': 110.0}})
>>> s = pd.Series(
... [100.0, 110.0, 120.0, 110.0],
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If ruff can't handle {{, it might be better to open an issue at ruff instead of re-writing the documentation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True but IMO I think it's okay to rewrite these ones for now just to avoid the potential {{ confusion for future contributors

@mroeschke mroeschke added this to the 3.0 milestone Jan 26, 2024
Copy link
Member

@rhshadrach rhshadrach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm - though I did not exhaustive check every change. Almost everything I see is overwhelmingly positive. The only negative I saw is that some examples became a bit long, and might be good to shorten at some point.

@mroeschke
Copy link
Member Author

Thanks for the reviews all. Going to merge to try out this ruff formatting but happy to follow up and update

@mroeschke mroeschke merged commit 4d3964e into pandas-dev:main Feb 8, 2024
48 checks passed
@mroeschke mroeschke deleted the sty/ruff branch February 8, 2024 16:42
Copy link
Member

@simonjayhawkins simonjayhawkins left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice

@@ -1794,14 +1794,14 @@ def normalize_keyword_aggregation(


def _make_unique_kwarg_list(
seq: Sequence[tuple[Any, Any]]
seq: Sequence[tuple[Any, Any]],
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this isn't a docstring. did ruff change this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I believe from ruff's upgrade to v0.1.13 in this PR

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

great.

pmhatre1 pushed a commit to pmhatre1/pandas-pmhatre1 that referenced this pull request May 7, 2024
* Bump ruff

* Format docstrings using ruff

* Fix double {{ examples

* Missed shift

* Add comma

* Remove import

* Remove old flake8 validation

* Remove unit test

* Revert "Remove unit test"

This reverts commit 6386676.

* Revert "Remove old flake8 validation"

This reverts commit d004398.

* docstring formatting

* Ignore formatting in scripts

* Ignore flake8 conflicts with ruff
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Code Style Code style, linting, code_checks Docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

DOC: fix EX03 errors in docstrings
5 participants