Document conventions in the FAQ (#8638)

Enumerates all rules defined in each convention in the FAQ. These lists
mirror
[pydocstyle](https://www.pydocstyle.org/en/latest/error_codes.html#default-conventions).

Closes https://github.com/astral-sh/ruff/issues/8573.

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]

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"?
 

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"