diff --git a/docs/faq.md b/docs/faq.md index 257da168baf2d..eb32c3e9311e8 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -260,7 +260,8 @@ Like isort, Ruff's import sorting is compatible with Black. Ruff does not yet support all of isort's configuration options, though it does support many of them. You can find the supported settings in the [API reference](settings.md#isort). -For example, you can set `known-first-party` like so: +For example, you can set [`known-first-party`](settings.md#known-first-party--isort-known-first-party-) +like so: ```toml [tool.ruff.lint] @@ -374,7 +375,8 @@ Found 3 errors. ## Does Ruff support NumPy- or Google-style docstrings? -Yes! To enforce a docstring convention, add the following to your `pyproject.toml`: +Yes! To enforce a docstring convention, add a [`convention`](settings.md#convention--pydocstyle-convention-) +setting following to your `pyproject.toml`: ```toml [tool.ruff.lint.pydocstyle] @@ -385,8 +387,8 @@ For example, if you're coming from flake8-docstrings, and your originating confi `--docstring-convention=numpy`, you'd instead set `convention = "numpy"` in your `pyproject.toml`, as above. -Alongside `convention`, you'll want to explicitly enable the `D` rule code prefix, since the `D` -rules are not enabled by default: +Alongside [`convention`](settings.md#convention--pydocstyle-convention-), you'll want to +explicitly enable the `D` rule code prefix, since the `D` rules are not enabled by default: ```toml [tool.ruff.lint] @@ -398,10 +400,10 @@ select = [ convention = "google" ``` -Setting a `convention` force-disables any rules that are incompatible with that convention, no -matter how they're provided, which avoids accidental incompatibilities and simplifies configuration. -By default, no `convention` is set, and so the enabled rules are determined by the `select` setting -alone. +Setting a [`convention`](settings.md#convention--pydocstyle-convention-) force-disables any rules +that are incompatible with that convention, no matter how they're provided, which avoids accidental +incompatibilities and simplifies configuration. By default, no [`convention`](settings.md#convention--pydocstyle-convention-) +is set, and so the enabled rules are determined by the [`select`](settings.md#select) setting alone. ## What is "preview"? @@ -457,7 +459,8 @@ For more, see the [`dirs`](https://docs.rs/dirs/4.0.0/dirs/fn.config_dir.html) c Ruff labels fixes as "safe" and "unsafe". By default, Ruff will fix all violations for which safe fixes are available, while unsafe fixes can be enabled via the [`unsafe-fixes`](settings.md#unsafe-fixes) -setting, or passing the `--unsafe-fixes` flag to `ruff check`. For more, see [the fix documentation](configuration.md#fixes). +setting, or passing the [`--unsafe-fixes`](settings.md#unsafe-fixes) flag to `ruff check`. For +more, see [the fix documentation](configuration.md#fixes). Even still, given the dynamic nature of Python, it's difficult to have _complete_ certainty when making changes to code, even for seemingly trivial fixes. If a "safe" fix breaks your code, please diff --git a/docs/linter.md b/docs/linter.md index 80a12cbf4d195..d73c9bb1b0104 100644 --- a/docs/linter.md +++ b/docs/linter.md @@ -46,7 +46,7 @@ formats. Ruff will automatically disable any conflicting rules when `ALL` is ena If you're wondering how to configure Ruff, here are some **recommended guidelines**: -- Prefer `select` over `extend-select` to make your rule set explicit. +- Prefer [`select`](settings.md#select) over [`extend-select`](settings.md#extend-select) to make your rule set explicit. - Use `ALL` with discretion. Enabling `ALL` will implicitly enable new rules whenever you upgrade. - Start with a small set of rules (`select = ["E", "F"]`) and add a category at-a-time. For example, you might consider expanding to `select = ["E", "F", "B"]` to enable the popular flake8-bugbear @@ -73,14 +73,15 @@ select = [ ] ``` -To resolve the enabled rule set, Ruff may need to reconcile `select` and `ignore` from a variety -of sources, including the current `pyproject.toml`, any inherited `pyproject.toml` files, and the -CLI (e.g., `--select`). +To resolve the enabled rule set, Ruff may need to reconcile [`select`](settings.md#select) and +[`ignore`](settings.md#ignore) from a variety of sources, including the current `pyproject.toml`, +any inherited `pyproject.toml` files, and the CLI (e.g., [`--select`](settings.md#select)). -In those scenarios, Ruff uses the "highest-priority" `select` as the basis for the rule set, and -then applies `extend-select` and `ignore` adjustments. CLI options are given -higher priority than `pyproject.toml` options, and the current `pyproject.toml` file is given higher -priority than any inherited `pyproject.toml` files. +In those scenarios, Ruff uses the "highest-priority" [`select`](settings.md#select) as the basis for +the rule set, and then applies [`extend-select`](settings.md#extend-select) and +[`ignore`](settings.md#ignore) adjustments. CLI options are given higher priority than +`pyproject.toml` options, and the current `pyproject.toml` file is given higher priority than any +inherited `pyproject.toml` files. For example, given the following `pyproject.toml` file: @@ -111,9 +112,12 @@ whether a rule supports fixing, see [_Rules_](rules.md). ### Fix safety -Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code will be retained when applying safe fixes, but the meaning could be changed when applying unsafe fixes. +Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code will be retained when +applying safe fixes, but the meaning could be changed when applying unsafe fixes. -For example, [`unnecessary-iterable-allocation-for-first-element`](rules/unnecessary-iterable-allocation-for-first-element.md) (`RUF015`) is a rule which checks for potentially unperformant use of `list(...)[0]`. The fix replaces this pattern with `next(iter(...))` which can result in a drastic speedup: +For example, [`unnecessary-iterable-allocation-for-first-element`](rules/unnecessary-iterable-allocation-for-first-element.md) +(`RUF015`) is a rule which checks for potentially unperformant use of `list(...)[0]`. The fix +replaces this pattern with `next(iter(...))` which can result in a drastic speedup: ```shell $ python -m timeit "head = list(range(99999999))[0]" @@ -170,8 +174,9 @@ You may use prefixes to select rules as well, e.g., `F` can be used to promote f ### Disabling fixes -To limit the set of rules that Ruff should fix, use the [`fixable`](settings.md#fixable) and [`unfixable`](settings.md#unfixable) settings, along with their [`extend-fixable`](settings.md#extend-fixable) and [`extend-unfixable`](settings.md#extend-unfixable) -variants. +To limit the set of rules that Ruff should fix, use the [`fixable`](settings.md#fixable) and +[`unfixable`](settings.md#unfixable) settings, along with their [`extend-fixable`](settings.md#extend-fixable) +and [`extend-unfixable`](settings.md#extend-unfixable) variants. For example, the following configuration would enable fixes for all rules except [`unused-imports`](rules/unused-import.md) (`F401`):