diff --git a/crates/ruff_workspace/src/options.rs b/crates/ruff_workspace/src/options.rs index 05094e145b48d..25a76de206c98 100644 --- a/crates/ruff_workspace/src/options.rs +++ b/crates/ruff_workspace/src/options.rs @@ -2383,10 +2383,10 @@ pub struct PydocstyleOptions { /// Whether to use Google-style or NumPy-style conventions or the [PEP 257](https://peps.python.org/pep-0257/) /// defaults when analyzing docstring sections. /// - /// Enabling a convention will force-disable any rules that are not - /// included in the specified convention. As such, the intended use is - /// to enable a convention and then selectively disable any additional - /// rules on top of it. + /// Enabling a convention will disable all rules that are not included in + /// the specified convention. As such, the intended workflow is to enable a + /// convention and then selectively enable or disable any additional rules + /// on top of it. /// /// For example, to use Google-style conventions but avoid requiring /// documentation for every function parameter: @@ -2405,9 +2405,9 @@ pub struct PydocstyleOptions { /// convention = "google" /// ``` /// - /// To modify a convention (i.e., to enable an additional rule that's excluded - /// from the convention by default), select the desired rule via its fully - /// qualified rule code (e.g., `D400` instead of `D4` or `D40`): + /// To enable an additional rule that's excluded from the convention, + /// select the desired rule via its fully qualified rule code (e.g., + /// `D400` instead of `D4` or `D40`): /// /// ```toml /// [tool.ruff.lint] diff --git a/docs/faq.md b/docs/faq.md index 86c8c389f1727..fe4b0b0ab1125 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -450,12 +450,43 @@ as above. Alongside [`convention`](settings.md#pydocstyle-convention), you'll want to explicitly enable the `D` rule code prefix, since the `D` rules are not enabled by default: +=== "pyproject.toml" + + ```toml + [tool.ruff.lint] + select = ["D"] + + [tool.ruff.lint.pydocstyle] + convention = "google" + ``` + +=== "ruff.toml" + + ```toml + [lint] + select = ["D"] + + [lint.pydocstyle] + convention = "google" + ``` + +Enabling a [`convention`](settings.md#pydocstyle-convention) will disable any rules that are not +included in the specified convention. As such, the intended workflow is to enable a convention and +then selectively enable or disable any additional rules on top of it: + === "pyproject.toml" ```toml [tool.ruff.lint] select = [ "D", + # Augment the convention by requiring an imperative mood for all docstrings. + "D401", + ] + + ignore = [ + # Relax the convention by _not_ requiring documentation for every function parameter. + "D417", ] [tool.ruff.lint.pydocstyle] @@ -468,16 +499,65 @@ explicitly enable the `D` rule code prefix, since the `D` rules are not enabled [lint] select = [ "D", + # Augment the convention by requiring an imperative mood for all docstrings. + "D401", + ] + + ignore = [ + # Relax the convention by _not_ requiring documentation for every function parameter. + "D417", ] [lint.pydocstyle] convention = "google" ``` -Setting a [`convention`](settings.md#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#pydocstyle-convention) -is set, and so the enabled rules are determined by the [`select`](settings.md#select) setting alone. +The PEP 257 convention includes all `D` errors apart from: +[`D203`](rules/one-blank-line-before-class.md), +[`D212`](rules/multi-line-summary-first-line.md), +[`D213`](rules/multi-line-summary-second-line.md), +[`D214`](rules/section-not-over-indented.md), +[`D215`](rules/section-underline-not-over-indented.md), +[`D404`](rules/docstring-starts-with-this.md), +[`D405`](rules/capitalize-section-name.md), +[`D406`](rules/new-line-after-section-name.md), +[`D407`](rules/dashed-underline-after-section.md), +[`D408`](rules/section-underline-after-name.md), +[`D409`](rules/section-underline-matches-section-length.md), +[`D410`](rules/no-blank-line-after-section.md), +[`D411`](rules/no-blank-line-before-section.md), +[`D413`](rules/no-blank-line-after-section.md), +[`D415`](rules/ends-in-punctuation.md), +[`D416`](rules/section-name-ends-in-colon.md), and +[`D417`](rules/undocumented-param.md). + +The NumPy convention includes all `D` errors apart from: +[`D107`](rules/undocumented-public-init.md), +[`D203`](rules/one-blank-line-before-class.md), +[`D212`](rules/multi-line-summary-first-line.md), +[`D213`](rules/multi-line-summary-second-line.md), +[`D402`](rules/no-signature.md), +[`D413`](rules/no-blank-line-after-section.md), +[`D415`](rules/ends-in-punctuation.md), +[`D416`](rules/section-name-ends-in-colon.md), and +[`D417`](rules/undocumented-param.md). + +The Google convention includes all `D` errors apart from: +[`D203`](rules/one-blank-line-before-class.md), +[`D204`](rules/one-blank-line-after-class.md), +[`D213`](rules/multi-line-summary-second-line.md), +[`D215`](rules/section-underline-not-over-indented.md), +[`D400`](rules/ends-in-period.md), +[`D401`](rules/non-imperative-mood.md), +[`D404`](rules/docstring-starts-with-this.md), +[`D406`](rules/new-line-after-section-name.md), +[`D407`](rules/dashed-underline-after-section.md), +[`D408`](rules/section-underline-after-name.md), +[`D409`](rules/section-underline-matches-section-length.md), and +[`D413`](rules/no-blank-line-after-section.md). + +By default, no [`convention`](settings.md#pydocstyle-convention) is set, and so the enabled rules +are determined by the [`select`](settings.md#select) setting alone. ## What is "preview"? diff --git a/ruff.schema.json b/ruff.schema.json index 34f6ebcd959ab..989b21078fcab 100644 --- a/ruff.schema.json +++ b/ruff.schema.json @@ -2241,7 +2241,7 @@ "type": "object", "properties": { "convention": { - "description": "Whether to use Google-style or NumPy-style conventions or the [PEP 257](https://peps.python.org/pep-0257/) defaults when analyzing docstring sections.\n\nEnabling a convention will force-disable any rules that are not included in the specified convention. As such, the intended use is to enable a convention and then selectively disable any additional rules on top of it.\n\nFor example, to use Google-style conventions but avoid requiring documentation for every function parameter:\n\n```toml [tool.ruff.lint] # Enable all `pydocstyle` rules, limiting to those that adhere to the # Google convention via `convention = \"google\"`, below. select = [\"D\"]\n\n# On top of the Google convention, disable `D417`, which requires # documentation for every function parameter. ignore = [\"D417\"]\n\n[tool.ruff.lint.pydocstyle] convention = \"google\" ```\n\nTo modify a convention (i.e., to enable an additional rule that's excluded from the convention by default), select the desired rule via its fully qualified rule code (e.g., `D400` instead of `D4` or `D40`):\n\n```toml [tool.ruff.lint] # Enable D400 on top of the Google convention. extend-select = [\"D400\"]\n\n[tool.ruff.lint.pydocstyle] convention = \"google\" ```", + "description": "Whether to use Google-style or NumPy-style conventions or the [PEP 257](https://peps.python.org/pep-0257/) defaults when analyzing docstring sections.\n\nEnabling a convention will disable all rules that are not included in the specified convention. As such, the intended workflow is to enable a convention and then selectively enable or disable any additional rules on top of it.\n\nFor example, to use Google-style conventions but avoid requiring documentation for every function parameter:\n\n```toml [tool.ruff.lint] # Enable all `pydocstyle` rules, limiting to those that adhere to the # Google convention via `convention = \"google\"`, below. select = [\"D\"]\n\n# On top of the Google convention, disable `D417`, which requires # documentation for every function parameter. ignore = [\"D417\"]\n\n[tool.ruff.lint.pydocstyle] convention = \"google\" ```\n\nTo enable an additional rule that's excluded from the convention, select the desired rule via its fully qualified rule code (e.g., `D400` instead of `D4` or `D40`):\n\n```toml [tool.ruff.lint] # Enable D400 on top of the Google convention. extend-select = [\"D400\"]\n\n[tool.ruff.lint.pydocstyle] convention = \"google\" ```", "anyOf": [ { "$ref": "#/definitions/Convention"