diff --git a/README.md b/README.md index c70fa4709b..292afee872 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ pip install ruff ``` You can also install Ruff via [Homebrew](https://formulae.brew.sh/formula/ruff), [Conda](https://anaconda.org/conda-forge/ruff), -and with [a variety of other package managers](https://beta.ruff.rs/docs/installation-and-usage/). +and with [a variety of other package managers](https://beta.ruff.rs/docs/installation/). ### Usage @@ -143,7 +143,7 @@ Ruff can also be used as a [pre-commit](https://pre-commit.com) hook: ``` Ruff can also be used as a [VS Code extension](https://github.com/charliermarsh/ruff-vscode) or -with other editors through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp). +alongside any other editor through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp). ### Configuration diff --git a/docs/.gitignore b/docs/.gitignore index 905d0d3dbb..e6a32bb303 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,7 +1,8 @@ * !assets !requirements.txt +!configuration.md !editor-integrations.md !faq.md -!configuration.md -!installation-and-usage.md +!installation.md +!usage.md diff --git a/docs/configuration.md b/docs/configuration.md index b379688732..88cc89d706 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,11 +1,13 @@ +# Configuring Ruff + Ruff can be configured via a `pyproject.toml` file, a `ruff.toml` file, or through the command line. For a complete enumeration of the available configuration options, see [_Settings_](/docs/settings/). -### Configure via `pyproject.toml` +### Via `pyproject.toml` -If left unspecified, the default configuration is equivalent to: +If left unspecified, Ruff's default configuration is equivalent to: ```toml [tool.ruff] @@ -89,16 +91,18 @@ select = ["E", "F", "Q"] docstring-quotes = "double" ``` +For a complete enumeration of the available configuration options, see +[_Settings_](/docs/settings/). + Ruff mirrors Flake8's rule code system, in which each rule code consists of a one-to-three letter prefix, followed by three digits (e.g., `F401`). The prefix indicates that "source" of the rule (e.g., `F` for Pyflakes, `E` for pycodestyle, `ANN` for flake8-annotations). The set of enabled -rules is determined by the `select` and `ignore` options, which support both the full code (e.g., -`F401`) and the prefix (e.g., `F`). +rules is determined by the `select` and `ignore` options, which accept either the full code (e.g., +`F401`) or the prefix (e.g., `F`). -As a special-case, Ruff also supports the `ALL` code, which enables all rules. Note that some of the +As a special-case, Ruff also supports the `ALL` code, which enables all rules. Note that some pydocstyle rules conflict (e.g., `D203` and `D211`) as they represent alternative docstring -formats. Enabling `ALL` without further configuration may result in suboptimal behavior, especially -for the pydocstyle plugin. +formats. Ruff will automatically disable any conflicting rules when `ALL` is enabled. If you're wondering how to configure Ruff, here are some **recommended guidelines**: @@ -111,11 +115,13 @@ If you're wondering how to configure Ruff, here are some **recommended guideline * By default, Ruff's autofix is aggressive. If you find that it's too aggressive for your liking, consider turning off autofix for specific rules or categories (see the [_FAQ_](/docs/faq/#ruff-tried-to-fix-something-but-it-broke-my-code-what-should-i-do)). -### Configure via `ruff.toml` +### Via `ruff.toml` As an alternative to `pyproject.toml`, Ruff will also respect a `ruff.toml` file, which implements -an equivalent schema (though the `[tool.ruff]` hierarchy can be omitted). For example, the -`pyproject.toml` described above would be represented via the following `ruff.toml`: +an equivalent schema (though the `[tool.ruff]` hierarchy can be omitted). + +For example, the `pyproject.toml` described above would be represented via the following +`ruff.toml`: ```toml # Enable flake8-bugbear (`B`) rules. @@ -138,8 +144,8 @@ For a complete enumeration of the available configuration options, see ### Command-line interface -Some configuration settings can be provided via the command-line, such as those related to -rule enablement and disablement, file discovery, logging level, and more: +Some configuration options can be provided via the command-line, such as those related to rule +enablement and disablement, file discovery, logging level, and more: ```shell ruff check path/to/code/ --select F401 --select F403 --quiet @@ -265,7 +271,7 @@ Log levels: Similar to [ESLint](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#cascading-and-hierarchy), Ruff supports hierarchical configuration, such that the "closest" `pyproject.toml` file in the directory hierarchy is used for every individual file, with all paths in the `pyproject.toml` file -(e.g., `exclude` globs, `src` paths) being resolved relative to the directory containing the +(e.g., `exclude` globs, `src` paths) being resolved relative to the directory containing that `pyproject.toml` file. There are a few exceptions to these rules: @@ -312,7 +318,7 @@ By default, Ruff will also skip any files that are omitted via `.ignore`, `.giti Files that are passed to `ruff` directly are always linted, regardless of the above criteria. For example, `ruff check /path/to/excluded/file.py` will always lint `file.py`. -### Rule resolution +### Rule selection The set of enabled rules is controlled via the [`select`](/docs/settings#select) and [`ignore`](/docs/settings#ignore) settings, along with the @@ -341,7 +347,7 @@ Running `ruff check --select F401` would result in Ruff enforcing `F401`, and no Running `ruff check --extend-select B` would result in Ruff enforcing the `E`, `F`, and `B` rules, with the exception of `F401`. -### Suppressing errors +### Error suppression To omit a lint rule entirely, add it to the "ignore" list via [`ignore`](/docs/settings#ignore) or [`extend-ignore`](/docs/settings#extend-ignore), either on the command-line @@ -391,7 +397,7 @@ setting, which enables the same functionality via a `pyproject.toml` file. Note that Ruff will also respect Flake8's `# flake8: noqa` directive, and will treat it as equivalent to `# ruff: noqa`. -#### Automatic error suppression +#### Automatic `noqa` management Ruff supports several workflows to aid in `noqa` management. diff --git a/docs/installation-and-usage.md b/docs/installation-and-usage.md deleted file mode 100644 index c3a792ff7d..0000000000 --- a/docs/installation-and-usage.md +++ /dev/null @@ -1,76 +0,0 @@ -### Installation - -Ruff is available as [`ruff`](https://pypi.org/project/ruff/) on PyPI: - -```shell -pip install ruff -``` - -For **macOS Homebrew** and **Linuxbrew** users, Ruff is also available as [`ruff`](https://formulae.brew.sh/formula/ruff) on Homebrew: - -```shell -brew install ruff -``` - -For **Conda** users, Ruff is also available as [`ruff`](https://anaconda.org/conda-forge/ruff) on -`conda-forge`: - -```shell -conda install -c conda-forge ruff -``` - -For **Arch Linux** users, Ruff is also available as [`ruff`](https://archlinux.org/packages/community/x86_64/ruff/) -on the official repositories: - -```shell -pacman -S ruff -``` - -For **Alpine** users, Ruff is also available as [`ruff`](https://pkgs.alpinelinux.org/package/edge/testing/x86_64/ruff) -on the testing repositories: - -```shell -apk add ruff -``` - -[![Packaging status](https://repology.org/badge/vertical-allrepos/ruff-python-linter.svg?exclude_unsupported=1)](https://repology.org/project/ruff-python-linter/versions) - -### Usage - -To run Ruff, try any of the following: - -```shell -ruff check . # Lint all files in the current directory (and any subdirectories) -ruff check path/to/code/ # Lint all files in `/path/to/code` (and any subdirectories) -ruff check path/to/code/*.py # Lint all `.py` files in `/path/to/code` -ruff check path/to/code/to/file.py # Lint `file.py` -``` - -You can run Ruff in `--watch` mode to automatically re-run on-change: - -```shell -ruff check path/to/code/ --watch -``` - -Ruff also works with [pre-commit](https://pre-commit.com): - -```yaml -- repo: https://github.com/charliermarsh/ruff-pre-commit - # Ruff version. - rev: 'v0.0.252' - hooks: - - id: ruff -``` - -Or, to enable autofix: - -```yaml -- repo: https://github.com/charliermarsh/ruff-pre-commit - # Ruff version. - rev: 'v0.0.252' - hooks: - - id: ruff - args: [--fix, --exit-non-zero-on-fix] -``` - -Note that Ruff's pre-commit hook should run before Black, isort, and other formatting tools. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000000..689d04c4b0 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,36 @@ +# Installing Ruff + +Ruff is available as [`ruff`](https://pypi.org/project/ruff/) on PyPI: + +```shell +pip install ruff +``` + +For **macOS Homebrew** and **Linuxbrew** users, Ruff is also available as [`ruff`](https://formulae.brew.sh/formula/ruff) on Homebrew: + +```shell +brew install ruff +``` + +For **Conda** users, Ruff is also available as [`ruff`](https://anaconda.org/conda-forge/ruff) on +`conda-forge`: + +```shell +conda install -c conda-forge ruff +``` + +For **Arch Linux** users, Ruff is also available as [`ruff`](https://archlinux.org/packages/community/x86_64/ruff/) +on the official repositories: + +```shell +pacman -S ruff +``` + +For **Alpine** users, Ruff is also available as [`ruff`](https://pkgs.alpinelinux.org/package/edge/testing/x86_64/ruff) +on the testing repositories: + +```shell +apk add ruff +``` + +[![Packaging status](https://repology.org/badge/vertical-allrepos/ruff-python-linter.svg?exclude_unsupported=1)](https://repology.org/project/ruff-python-linter/versions) diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000000..2830bc84fc --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,42 @@ +# Using Ruff + +To run Ruff, try any of the following: + +```shell +ruff check . # Lint all files in the current directory (and any subdirectories) +ruff check path/to/code/ # Lint all files in `/path/to/code` (and any subdirectories) +ruff check path/to/code/*.py # Lint all `.py` files in `/path/to/code` +ruff check path/to/code/to/file.py # Lint `file.py` +``` + +You can run Ruff in `--watch` mode to automatically re-run on-change: + +```shell +ruff check path/to/code/ --watch +``` + +Ruff can also be used as a [pre-commit](https://pre-commit.com) hook: + +```yaml +- repo: https://github.com/charliermarsh/ruff-pre-commit + # Ruff version. + rev: 'v0.0.252' + hooks: + - id: ruff +``` + +Or, to enable autofix: + +```yaml +- repo: https://github.com/charliermarsh/ruff-pre-commit + # Ruff version. + rev: 'v0.0.252' + hooks: + - id: ruff + args: [--fix, --exit-non-zero-on-fix] +``` + +Note that Ruff's pre-commit hook should run before Black, isort, and other formatting tools. + +Ruff can also be used as a [VS Code extension](https://github.com/charliermarsh/ruff-vscode) or +alongside any other editor through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp). diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index 406f4ae991..fb8e9d963e 100644 --- a/scripts/generate_mkdocs.py +++ b/scripts/generate_mkdocs.py @@ -18,7 +18,8 @@ class Section(NamedTuple): SECTIONS: list[Section] = [ Section("Overview", "index.md", generated=True), - Section("Installation and Usage", "installation-and-usage.md", generated=False), + Section("Installation", "installation.md", generated=False), + Section("Usage", "usage.md", generated=False), Section("Configuration", "configuration.md", generated=False), Section("Rules", "rules.md", generated=True), Section("Settings", "settings.md", generated=True),