Skip to content

Docs normalization #18831

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

Merged
merged 29 commits into from
Jun 20, 2025
Merged

Docs normalization #18831

merged 29 commits into from
Jun 20, 2025

Conversation

MeGaGiGaGon
Copy link
Contributor

Summary

While working on a detector for #15584, I noticed several inconsistencies in the docs, so this PR fixes them.

  • Blank line between doc comment and #[derive(ViolationMetadata)]
  • Empty doc comment before #[derive(ViolationMetadata)]
  • ## Fix Safety instead of ## Fix safety

Test Plan

N/A, no functionality/tests affected

@MeGaGiGaGon MeGaGiGaGon requested a review from AlexWaygood as a code owner June 20, 2025 18:56
@ntBre ntBre added the documentation Improvements or additions to documentation label Jun 20, 2025
Copy link
Contributor

github-actions bot commented Jun 20, 2025

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Copy link
Member

@AlexWaygood AlexWaygood left a comment

Choose a reason for hiding this comment

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

Thanks! One of these changes feels unnecessary to me, but the rest LGTM :-)

Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure there's a need to change this file -- we just end up with a very small Fix safety section, and I think the content in that paragraph naturally fits with the content of the preceding two paragraphs. I don't think it's essential that every rule is totally consistent in the docs sections it has.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The main reason I did is for the consistency - like what I've been doing, if you are writing a tool to try and detect all rules missing the section, it's a one-off edge case, since in the searching I did I could not find another rule that had this format.

Copy link
Member

Choose a reason for hiding this comment

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

Eh, fair enough. It would certainly be nice to enforce (one day...) in CI that all rules which are sometimes unsafe have a Fix safety section in their docs explaining why.

@AlexWaygood AlexWaygood merged commit ef785d2 into astral-sh:main Jun 20, 2025
35 checks passed
@MeGaGiGaGon MeGaGiGaGon deleted the docs-normalization branch June 20, 2025 20:56
dcreager added a commit that referenced this pull request Jun 20, 2025
* main:
  Handle parenthesized arguments in `remove_argument` (#18805)
  Unify helpers modules (#18835)
  Normalize some docs sections (#18831)
  [`flake8_pyi`] Fix `PYI041`'s fix causing TypeError with `None | None | ...` (#18637)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants