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

Docs (linter.md): clarify that Python files are always searched for in subdirectories #15882

Merged
merged 2 commits into from
Feb 4, 2025

Conversation

anordin95
Copy link
Contributor

Nits related to clarity of which files are linted

Hi!

I noticed no mention of recursing through sub-dirs and only the fourth example: ruff check path/to/code/ included the phrase: "and any subdirectories" leading me to believe only providing a path would recurse and the others would not. I don't think that's the actual behavior. It does feel a bit repetitive to say so in each example and in the intro paragraph, but I do somewhat like the clarity.

Also, I opted to remove the "all" from "Lint all files in the current directory." (and others) since I presume it doesn't lint all files, only "all discovered Python files". Without the "all", I think it's clear many files will be linted, and it gives
a hint that further logic exists for filtering.

@AlexWaygood AlexWaygood added the documentation Improvements or additions to documentation label Feb 3, 2025
@AlexWaygood AlexWaygood changed the title nits: linter.md Docs nits in linter.md Feb 3, 2025
docs/linter.md Outdated
Comment on lines 10 to 20
`ruff check` is the primary entrypoint to the Ruff linter. It accepts a list of files or
directories, and lints all discovered Python files, optionally fixing any fixable errors:
directories, and lints all discovered Python files (including those in subdirectories), optionally
fixing any fixable errors:

```console
$ ruff check # Lint all files in the current directory.
$ ruff check --fix # Lint all files in the current directory, and fix any fixable errors.
$ ruff check --watch # Lint all files in the current directory, and re-lint on change.
$ ruff check path/to/code/ # Lint all files in `path/to/code` (and any subdirectories).
$ ruff check # Lint files in the current directory and any subdirectories.
$ ruff check --fix # Lint files in the current directory and any subdirectories and fix any fixable errors.
$ ruff check --watch # Lint files in the current directory and any subdirectories and re-lint on change.
$ ruff check path/to/code/ # Lint files in `path/to/code` and any subdirectories.
```
Copy link
Member

@AlexWaygood AlexWaygood Feb 3, 2025

Choose a reason for hiding this comment

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

I can see how this is unclear on main, but the suggested rewording here does feel a little repetitive now. What about something like this?

`ruff check` is the primary entrypoint to the Ruff linter. It accepts a list of files or
directories, and lints all discovered Python files, optionally fixing any fixable errors.
When linting a directory, Ruff searches for Python files recursively in that directory
and all its subdirectories:

```console
$ ruff check                  # Lint all files in the current directory.
$ ruff check --fix            # Lint all files in the current directory, and fix any fixable errors.
$ ruff check --watch          # Lint all files in the current directory, and re-lint on change.
$ ruff check path/to/code/    # Lint all files in `path/to/code`
```

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Mmm, yes that's better! Well done :)

Copy link
Contributor Author

@anordin95 anordin95 Feb 3, 2025

Choose a reason for hiding this comment

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

PS do you have opinions on:
Lint all files in the current directory.
vs.
Lint files starting from the current directory.

I prefer the latter since it hints there is some filtering and recursion without losing clarity, e.g. only Python files, respect .gitignore, etc.

@AlexWaygood AlexWaygood changed the title Docs nits in linter.md Docs (linter.md): clarify that Python files are always searched for in subdirectories Feb 3, 2025
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!

@AlexWaygood AlexWaygood enabled auto-merge (squash) February 4, 2025 15:33
@AlexWaygood AlexWaygood merged commit 9d83e76 into astral-sh:main Feb 4, 2025
20 checks passed
dcreager added a commit that referenced this pull request Feb 4, 2025
* main: (66 commits)
  [red-knot] Use ternary decision diagrams (TDDs) for visibility constraints (#15861)
  [`pyupgrade`] Rename private type parameters in PEP 695 generics (`UP049`) (#15862)
  Simplify the `StringFlags` trait (#15944)
  [`flake8-pyi`] Make `PYI019` autofixable for `.py` files in preview mode as well as stubs (#15889)
  Docs (`linter.md`): clarify that Python files are always searched for in subdirectories (#15882)
  [`flake8-pyi`] Make PEP-695 functions with multiple type parameters fixable by PYI019 again (#15938)
  [red-knot] Use unambiguous invalid-syntax-construct for suppression comment test (#15933)
  Make `Binding::range()` point to the range of a type parameter's name, not the full type parameter (#15935)
  Update black deviations (#15928)
  [red-knot] MDTest: Fix line numbers in error messages (#15932)
  Preserve triple quotes and prefixes for strings (#15818)
  [red-knot] Hand-written MDTest parser (#15926)
  [`pylint`] Fix missing parens in unsafe fix for `unnecessary-dunder-call` (`PLC2801`) (#15762)
  nit: docs for ignore & select (#15883)
  [airflow] `BashOperator` has been moved to `airflow.providers.standard.operators.bash.BashOperator` (AIR302) (#15922)
  [`flake8-logging`] `.exception()` and `exc_info=` outside exception handlers (`LOG004`, `LOG014`) (#15799)
  [red-knot] Enforce specifying paths for mdtest code blocks in a separate preceding line (#15890)
  [red-knot] Internal refactoring of visibility constraints API (#15913)
  [red-knot] Implicit instance attributes (#15811)
  [`flake8-comprehensions`] Handle extraneous parentheses around list comprehension (`C403`) (#15877)
  ...
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.

2 participants