[tool.ruff.lint] usage in docs is inconsistent

[jonprindiville]

Hey friends,

It seems like with the arrival of the formatter (neat!) the linter-specific configs are going to be nested under tool.ruff.lint rather than directly under tool.ruff? I think that the docs are currently somewhat inconsistent with that change, though.

For instance:

• select is under tool.ruff.lint in the "Configuring Ruff" doc, but
• select seems like a top-level settings in the "Settings" doc

Also in the "Configuring Ruff" doc is a mention of tool.ruff.lint.per-file-ignores and tool.ruff.lint.flake8-quotes but when I go to the Settings section to look for those, it seems like they are still under tool.ruff directly: per-file-ignores, flake8-quotes

--

From snooping around in PRs (#7549) it seems like maybe that section is experimental and we're still deciding whether/how to show it?

I don't really know about the current status of that thinking.

I do think that current state of docs having a mix of tool.ruff.lint and tool.ruff is a bit confusing. Maybe can get some explicit language explaining the state of tool.ruff.lint versus tool.ruff? They still get merged together for v0.1.3?

(Anyhow, thanks! Ruff is neat!)

[T-256]

Thanks for detailed info, I believe it's fixed on #8324 and will be included in coming documentation release.

it seems like maybe that section is experimental and we're still deciding whether/how to show it?

No, it's now preferable! the top-level lint names will be deprecated in #7651

[T-256]

Maybe can get some explicit language explaining the state of tool.ruff.lint versus tool.ruff? They still get merged together for v0.1.3?

Yes, always do tool.ruff.lint.option-name.
Currently, top-level names used in most of projects (because .lint is new), But in coming release we wouldn't have any top-level lint names in docs and later they will be deprecated.

[MichaReiser]

it seems like maybe that section is experimental and we're still deciding whether/how to show it?

Kind of yes. Using ruff.lint is the new preferred way, but we haven't promoted it more, because we're looking for feedback and want to have the possibility to make breaking changes to it, without it falling under our versioning policy (just yet).

I think the downside of this approach is what you pointed out, that we now a mixture in our documentation that leads to confusion and also doesn't make it clear that ruff.lint is experimental (and may change).

[jonprindiville]

Thanks for detailed info, I believe it's fixed on #8324 [...]

[...] in coming release we wouldn't have any top-level lint names in docs and later they will be deprecated.

Ah, great -- sounds like it's already headed towards a more consistent state, thanks all!

[charliermarsh]

This should be in a better state now 🤞

[Mr-Pepe]

For instance:

• select is under tool.ruff.lint in the "Configuring Ruff" doc, but
• select seems like a top-level settings in the "Settings" doc

That is still the case though.

[jonprindiville]

That is still the case though. [as of Dec 7, 2023]

☝️ That is true, I did see some inconsistencies linger for a bit after this issue got closed.

All of the cases I originally noted have been resolved at this point though. I can't find any others.

(I suspect we are good as of 0.2.0 because that's when the deprecation of the old names shows up in release notes?)