From edf31e226f97c4bbe969d211708811e3837d7c8f Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Fri, 19 Apr 2024 18:15:16 -0400 Subject: [PATCH] Improve documentation around custom isort sections --- crates/ruff_workspace/src/options.rs | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/crates/ruff_workspace/src/options.rs b/crates/ruff_workspace/src/options.rs index d349a8631ca8c4..27bfab9934a4ea 100644 --- a/crates/ruff_workspace/src/options.rs +++ b/crates/ruff_workspace/src/options.rs @@ -2257,7 +2257,31 @@ pub struct IsortOptions { // Tables are required to go last. /// A list of mappings from section names to modules. - /// By default custom sections are output last, but this can be overridden with `section-order`. + /// + /// By default, imports are categorized according to their type (e.g., `future`, `third-party`, + /// and so on). This setting allows you to group modules into custom sections, to augment or + /// override the built-in sections. + /// + /// For example, to group all testing utilities, you could create a `testing` section: + /// ```toml + /// testing = ["pytest", "hypothesis"] + /// ``` + /// + /// Custom sections should typically be inserted into the `section-order` list to ensure that + /// they're displayed as a standalone group and in the intended order, as in: + /// ```toml + /// section-order = [ + /// "future", + /// "standard-library", + /// "third-party", + /// "first-party", + /// "local-folder", + /// "testing" + /// ] + /// ``` + /// + /// If a custom section is omitted from `section-order`, imports in that section will be + /// assigned to the `default-section` (which defaults to `third-party`). #[option( default = "{}", value_type = "dict[str, list[str]]",