From cec6d1915612141154d525eff9ad328805277c5c Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Wed, 11 Mar 2026 19:40:51 -0400
Subject: [PATCH] Add pydocstyle and `W` rules to `ruff.toml`

Enable `D2xx` formatting rules to enforce piker's `'''`
multiline docstring convention: summary on second line
(D213), closing quotes on separate line (D209), blank
line between summary and description (D205).

Deats,
- select `D2` (whitespace/formatting) rule group plus
  cherry-picked `D402`/`D403`/`D419` content checks.
- ignore `D200` (allow multiline for short docstrings),
  `D203` (use `D211` instead), `D212` (use `D213`).
- skip `D1xx` (missing-docstring) to avoid noise and
  `D3xx` since `D300` conflicts with `'''` convention.
- add `W` rules for trailing-whitespace detection.

Also,
- enable `docstring-code-format` with 67-char width
  for code examples inside docstrings.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 ruff.toml | 60 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 43 insertions(+), 17 deletions(-)

diff --git a/ruff.toml b/ruff.toml
index b928ad00..f4d289d7 100644
--- a/ruff.toml
+++ b/ruff.toml
@@ -44,11 +44,43 @@ target-version = "py312"
 
 
 [lint]
-# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
-# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
-# McCabe complexity (`C901`) by default.
-select = ["E4", "E7", "E9", "F"]
-ignore = []
+select = [
+    # pycodestyle error subsets (pre-existing)
+    "E4", "E7", "E9",
+    # pyflakes (pre-existing)
+    "F",
+
+    # -- pydocstyle: enforce piker's ''' multiline style --
+    # D2xx whitespace and formatting rules; most are
+    # auto-fixable via `ruff check --fix`.
+    # NOTE: D1xx (missing-docstring) rules intentionally
+    # excluded to avoid noise across the existing codebase.
+    "D2",
+    # D4xx content checks (cherry-picked)
+    "D402",  # first line != function signature
+    "D403",  # capitalize first word
+    "D419",  # no empty docstrings
+    # NOTE: D3xx skipped entirely since D300 enforces
+    # triple-double-quotes `"""` which conflicts with
+    # piker's `'''` convention (the formatter's
+    # `quote-style = "single"` handles conversion).
+
+    # pycodestyle warnings
+    "W",
+]
+ignore = [
+    # -- pydocstyle ignores for piker conventions --
+    # piker ALWAYS uses multiline docstring style, never
+    # single-line, so disable the "fit on one line" rule.
+    "D200",
+    # piker uses NO blank line before class docstrings
+    # (D211) not 1-blank-line (D203); these conflict.
+    "D203",
+    # piker puts the summary on the SECOND line after
+    # an opening `'''` (D213); not on the same line as
+    # the opening quotes (D212); these conflict.
+    "D212",
+]
 ignore-init-module-imports = false
 
 [lint.per-file-ignores]
@@ -79,16 +111,10 @@ skip-magic-trailing-comma = false
 # Like Black, automatically detect the appropriate line ending.
 line-ending = "auto"
 
-# Enable auto-formatting of code examples in docstrings. Markdown,
-# reStructuredText code/literal blocks and doctests are all supported.
-#
-# This is currently disabled by default, but it is planned for this
-# to be opt-out in the future.
-docstring-code-format = false
+# Auto-format code examples inside docstrings
+# (>>> blocks, code fences, etc.)
+docstring-code-format = true
 
-# Set the line length limit used when formatting code snippets in
-# docstrings.
-#
-# This only has an effect when the `docstring-code-format` setting is
-# enabled.
-docstring-code-line-length = "dynamic"
+# Use piker's 67-char target for code inside docstrings
+# (only applies when `docstring-code-format = true`).
+docstring-code-line-length = 67