Add Markdown documentation for existing lint rules

[charliermarsh]

If we write documentation on the #[violation] macro:

/// ### What it does
/// Checks for `self.assertRaises(Exception)`.
///
/// ## Why is this bad?
/// `assertRaises(Exception)` can lead to your test passing even if the
/// code being tested is never executed due to a typo.
///
/// Either assert for a more specific exception (builtin or custom), use
/// `assertRaisesRegex` or the context manager form of `assertRaises`.
#[violation]
pub struct NoAssertRaisesException;

This explanation shows up with ruff rule B017, and in the docs:

• https://github.com/charliermarsh/ruff/blob/main/docs/rules/assert-raises-exception.md
• https://beta.ruff.rs/docs/rules/assert-raises-exception/

We'll track progress here:

• airflow
• eradicate
• flake8-2020
• flake8-annotations
• flake8-async
• flake8-bandit
• flake8-blind-except
• flake8-boolean-trap
• flake8-bugbear
• flake8-builtins
• flake8-commas
• flake8-comprehensions
• flake8-copyright
• flake8-datetimez
• flake8-debugger
• flake8-django
• flake8-errmsg
• flake8-executable
• flake8-fixme
• flake8-future-annotations
• flake8-gettext
• flake8-implicit-str-concat
• flake8-import-conventions
• flake8-logging-format
• flake8-no-pep420
• flake8-pie
• flake8-print
• flake8-pyi
• flake8-pytest-style
• flake8-quotes
• flake8-raise
• flake8-return
• flake8-self
• flake8-simplify
• flake8-slots
• flake8-tidy-imports
• flake8-todos
• flake8-type-checking
• flake8-unused-arguments
• flake8-use-pathlib
• flynt
• isort
• mccabe
• numpy
• pandas-vet
• pep8-naming
• perflint
• pycodestyle
• pydocstyle
• pyflakes
• pygrep-hooks
• pylint
• pyupgrade
• ruff
• tryceratops

[spaceone]

That's very nice!
In the README the rule is linked twice. Once for the code and once fore the human-readable-name. Isn't one link at the humann-readable-name enough? This would enable to double-click/select the rule name into copy&paste buffer instead of opening the link.

[charliermarsh]

We could link it once -- I don't feel strongly!

[charliermarsh]

(Making a concerted effort to add these for all new rules.)

[thatlittleboy]

Hi, I'm looking to do my part in contributing some docs~

Quick question: I noticed that in #2796 for example, there is a change to bare_except.rs and the OP added docs/rules/bare_except.md. Do I have to write the markdown file myself or is it a generated file (since it's largely replicated from the text in define_violation! macro)?

[charliermarsh]

Thanks! Everything is generated from the rustdoc in the macro, so no need to touch any Markdown. (We actually don’t even check in the generated Markdown anymore, so it won’t appear as part of any PRs — only need to write the rustdoc part, and the rest is taken care of for you when we generate the docs :))

[JonathanPlasse]

try.ceratops already has documented its rules in its documentation.

[charliermarsh]

👍 I'd prefer not to copy over their documentation though, would prefer to write our own. But we can look to theirs for guidance.

[harupy]

flake8-pytest-style is complete!

[charliermarsh]

It looks like we're down to 31 rules that lack documentation:

• call-with-shell-equals-true
• start-process-with-a-shell
• start-process-with-no-shell
• call-datetime-strptime-without-zone
• call-date-today
• call-date-fromtimestamp
• pass-statement-stub-body
• non-empty-stub-body
• typed-argument-default-in-stub
• pass-in-class-body
• argument-default-in-stub
• assignment-default-in-stub
• duplicate-union-member
• quoted-annotation-in-stub
• docstring-in-stub
• unassigned-special-variable-in-stub
• snake-case-type-alias
• t-suffixed-type-alias
• future-annotations-in-stub
• stub-body-multiple-statements
• no-return-argument-annotation-in-stub
• unannotated-assignment-in-stub
• string-or-bytes-too-long
• numeric-literal-too-long
• pytest-incorrect-fixture-name-underscore
• missing-whitespace
• unexpected-spaces-around-keyword-parameter-equals
• missing-whitespace-around-parameter-equals
• missing-whitespace-after-keyword
• io-error
• syntax-error