config: add new 'format-code-in-docstrings' knob

This commit does the plumbing to make a new formatting option,
'format-code-in-docstrings', available in the configuration for end
users. It is disabled by default (opt-in). It is opt-in at least
initially to reflect a conservative posture. The intent is to make it
opt-out at some point in the future.

The name was inspired by the name of a similar configuration in
rustfmt[1].

[1]: https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=#format_code_in_doc_comments

Author: BurntSushi

crates/ruff_workspace/src/configuration.rs

@@ -34,7 +34,7 @@ use ruff_linter::settings::{
 use ruff_linter::{
     fs, warn_user, warn_user_once, warn_user_once_by_id, RuleSelector, RUFF_PKG_VERSION,
 };
-use ruff_python_formatter::{MagicTrailingComma, QuoteStyle};
+use ruff_python_formatter::{DocstringCode, MagicTrailingComma, QuoteStyle};
 
 use crate::options::{
     Flake8AnnotationsOptions, Flake8BanditOptions, Flake8BugbearOptions, Flake8BuiltinsOptions,
@@ -180,6 +180,9 @@ impl Configuration {
             magic_trailing_comma: format
                 .magic_trailing_comma
                 .unwrap_or(format_defaults.magic_trailing_comma),
+            format_code_in_docstrings: format
+                .format_code_in_docstrings
+                .unwrap_or(format_defaults.format_code_in_docstrings),
         };
 
         let lint = self.lint;
@@ -1011,6 +1014,7 @@ pub struct FormatConfiguration {
     pub quote_style: Option<QuoteStyle>,
     pub magic_trailing_comma: Option<MagicTrailingComma>,
     pub line_ending: Option<LineEnding>,
+    pub format_code_in_docstrings: Option<DocstringCode>,
 }
 
 impl FormatConfiguration {
@@ -1037,6 +1041,13 @@ impl FormatConfiguration {
                 }
             }),
             line_ending: options.line_ending,
+            format_code_in_docstrings: options.format_code_in_docstrings.map(|yes| {
+                if yes {
+                    DocstringCode::Enabled
+                } else {
+                    DocstringCode::Disabled
+                }
+            }),
         })
     }
 
@@ -1050,6 +1061,9 @@ impl FormatConfiguration {
             quote_style: self.quote_style.or(other.quote_style),
             magic_trailing_comma: self.magic_trailing_comma.or(other.magic_trailing_comma),
             line_ending: self.line_ending.or(other.line_ending),
+            format_code_in_docstrings: self
+                .format_code_in_docstrings
+                .or(other.format_code_in_docstrings),
         }
     }
 }

crates/ruff_workspace/src/options.rs

@@ -2882,6 +2882,49 @@ pub struct FormatOptions {
         "#
     )]
     pub line_ending: Option<LineEnding>,
+
+    /// Whether to format code snippets in docstrings.
+    ///
+    /// When this is enabled, Python code in the format of doctests
+    /// within docstrings is automatically reformatted.
+    ///
+    /// For example, when this is enabled, the following code:
+    ///
+    /// ```python
+    /// def f(x):
+    ///     """
+    ///     Something about `f`. And an example:
+    ///
+    ///     >>> f(  x  )
+    ///     """
+    ///     pass
+    /// ```
+    ///
+    /// will be reformatted (assuming the rest of the options are set
+    /// to their defaults) as:
+    ///
+    /// ```python
+    /// def f(x):
+    ///     """
+    ///     Something about `f`. And an example:
+    ///
+    ///     >>> f(x)
+    ///     """
+    ///     pass
+    /// ```
+    ///
+    /// If a doctest contains invalid Python code or if the formatter would
+    /// otherwise write invalid Python code, then the doctest is ignored by
+    /// the formatter and kept as-is.
+    #[option(
+        default = "false",
+        value_type = "bool",
+        example = r#"
+            # Enable reformatting of code snippets in docstrings.
+            format-code-in-docstrings = true
+        "#
+    )]
+    pub format_code_in_docstrings: Option<bool>,
 }
 
 #[cfg(test)]

crates/ruff_workspace/src/settings.rs

@@ -5,7 +5,9 @@ use ruff_linter::settings::types::{FilePattern, FilePatternSet, SerializationFor
 use ruff_linter::settings::LinterSettings;
 use ruff_macros::CacheKey;
 use ruff_python_ast::PySourceType;
-use ruff_python_formatter::{MagicTrailingComma, PreviewMode, PyFormatOptions, QuoteStyle};
+use ruff_python_formatter::{
+    DocstringCode, MagicTrailingComma, PreviewMode, PyFormatOptions, QuoteStyle,
+};
 use ruff_source_file::find_newline;
 use std::path::{Path, PathBuf};
 
@@ -124,6 +126,8 @@ pub struct FormatterSettings {
     pub magic_trailing_comma: MagicTrailingComma,
 
     pub line_ending: LineEnding,
+
+    pub format_code_in_docstrings: DocstringCode,
 }
 
 impl FormatterSettings {
@@ -157,6 +161,7 @@ impl FormatterSettings {
             .with_preview(self.preview)
             .with_line_ending(line_ending)
             .with_line_width(self.line_width)
+            .with_docstring_code(self.format_code_in_docstrings)
     }
 }
 
@@ -173,6 +178,7 @@ impl Default for FormatterSettings {
             indent_width: default_options.indent_width(),
             quote_style: default_options.quote_style(),
             magic_trailing_comma: default_options.magic_trailing_comma(),
+            format_code_in_docstrings: default_options.docstring_code(),
         }
     }
 }