config: add new 'docstring-code-format' and 'docstring-code-line-length' knobs

This commit does the plumbing to make a new formatting option,
'docstring-code-format', 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.

This also adds a compansion option, 'docstring-code-line-length', that
permits setting a line length for reformatted code examples that is
distinct from the global setting. Its default value is 'dynamic', which
means reformatted code will respect the global line width, regardless of
the indent level of the enclosing docstring.

Author: BurntSushi

crates/ruff_cli/tests/format.rs

@@ -139,6 +139,99 @@ if condition:
     Ok(())
 }
 
+#[test]
+fn docstring_options() -> Result<()> {
+    let tempdir = TempDir::new()?;
+    let ruff_toml = tempdir.path().join("ruff.toml");
+    fs::write(
+        &ruff_toml,
+        r#"
+[format]
+docstring-code-format = true
+docstring-code-line-length = 20
+"#,
+    )?;
+
+    assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
+        .args(["format", "--config"])
+        .arg(&ruff_toml)
+        .arg("-")
+        .pass_stdin(r#"
+def f(x):
+    '''
+    Something about `f`. And an example:
+
+    .. code-block:: python
+
+        foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
+
+    Another example:
+
+    ```py
+    foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
+    ```
+
+    And another:
+
+    >>> foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
+    '''
+    pass
+"#), @r###"
+success: true
+exit_code: 0
+----- stdout -----
+def f(x):
+    """
+    Something about `f`. And an example:
+
+    .. code-block:: python
+
+        (
+            foo,
+            bar,
+            quux,
+        ) = this_is_a_long_line(
+            lion,
+            hippo,
+            lemur,
+            bear,
+        )
+
+    Another example:
+
+    ```py
+    (
+        foo,
+        bar,
+        quux,
+    ) = this_is_a_long_line(
+        lion,
+        hippo,
+        lemur,
+        bear,
+    )
+    ```
+
+    And another:
+
+    >>> (
+    ...     foo,
+    ...     bar,
+    ...     quux,
+    ... ) = this_is_a_long_line(
+    ...     lion,
+    ...     hippo,
+    ...     lemur,
+    ...     bear,
+    ... )
+    """
+    pass
+
+----- stderr -----
+"###);
+    Ok(())
+}
+
 #[test]
 fn mixed_line_endings() -> Result<()> {
     let tempdir = TempDir::new()?;

crates/ruff_python_formatter/src/options.rs

@@ -175,6 +175,12 @@ impl PyFormatOptions {
         self
     }
 
+    #[must_use]
+    pub fn with_docstring_code_line_width(mut self, line_width: DocstringCodeLineWidth) -> Self {
+        self.docstring_code_line_width = line_width;
+        self
+    }
+
     #[must_use]
     pub fn with_preview(mut self, preview: PreviewMode) -> Self {
         self.preview = preview;

crates/ruff_workspace/src/configuration.rs

@@ -34,7 +34,9 @@ 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, DocstringCodeLineWidth, MagicTrailingComma, QuoteStyle,
+};
 
 use crate::options::{
     Flake8AnnotationsOptions, Flake8BanditOptions, Flake8BugbearOptions, Flake8BuiltinsOptions,
@@ -189,6 +191,12 @@ impl Configuration {
             magic_trailing_comma: format
                 .magic_trailing_comma
                 .unwrap_or(format_defaults.magic_trailing_comma),
+            docstring_code_format: format
+                .docstring_code_format
+                .unwrap_or(format_defaults.docstring_code_format),
+            docstring_code_line_width: format
+                .docstring_code_line_width
+                .unwrap_or(format_defaults.docstring_code_line_width),
         };
 
         let lint = self.lint;
@@ -1020,6 +1028,8 @@ pub struct FormatConfiguration {
     pub quote_style: Option<QuoteStyle>,
     pub magic_trailing_comma: Option<MagicTrailingComma>,
     pub line_ending: Option<LineEnding>,
+    pub docstring_code_format: Option<DocstringCode>,
+    pub docstring_code_line_width: Option<DocstringCodeLineWidth>,
 }
 
 impl FormatConfiguration {
@@ -1046,6 +1056,14 @@ impl FormatConfiguration {
                 }
             }),
             line_ending: options.line_ending,
+            docstring_code_format: options.docstring_code_format.map(|yes| {
+                if yes {
+                    DocstringCode::Enabled
+                } else {
+                    DocstringCode::Disabled
+                }
+            }),
+            docstring_code_line_width: options.docstring_code_line_length,
         })
     }
 
@@ -1059,6 +1077,10 @@ 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),
+            docstring_code_format: self.docstring_code_format.or(other.docstring_code_format),
+            docstring_code_line_width: self
+                .docstring_code_line_width
+                .or(other.docstring_code_line_width),
         }
     }
 }

crates/ruff_workspace/src/options.rs

@@ -27,7 +27,7 @@ use ruff_linter::settings::types::{
 };
 use ruff_linter::{warn_user_once, RuleSelector};
 use ruff_macros::{CombineOptions, OptionsMetadata};
-use ruff_python_formatter::QuoteStyle;
+use ruff_python_formatter::{DocstringCodeLineWidth, QuoteStyle};
 
 use crate::settings::LineEnding;
 
@@ -2896,6 +2896,153 @@ pub struct FormatOptions {
         "#
     )]
     pub line_ending: Option<LineEnding>,
+
+    /// Whether to format code snippets in docstrings.
+    ///
+    /// When this is enabled, Python code examples within docstrings is
+    /// automatically reformatted.
+    ///
+    /// For example, when this is enabled, the following code:
+    ///
+    /// ```python
+    /// def f(x):
+    ///     """
+    ///     Something about `f`. And an example in doctest format:
+    ///
+    ///     >>> f(  x  )
+    ///
+    ///     Markdown is also supported:
+    ///
+    ///     ```py
+    ///     f(  x  )
+    ///     ```
+    ///
+    ///     As are reStructuredText literal blocks::
+    ///
+    ///         f(  x  )
+    ///
+    ///
+    ///     And reStructuredText code blocks:
+    ///
+    ///     .. code-block:: python
+    ///
+    ///         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 in doctest format:
+    ///
+    ///     >>> f(x)
+    ///
+    ///     Markdown is also supported:
+    ///
+    ///     ```py
+    ///     f(x)
+    ///     ```
+    ///
+    ///     As are reStructuredText literal blocks::
+    ///
+    ///         f(x)
+    ///
+    ///
+    ///     And reStructuredText code blocks:
+    ///
+    ///     .. code-block:: python
+    ///
+    ///         f(x)
+    ///     """
+    ///     pass
+    /// ```
+    ///
+    /// If a code snippt in a docstring contains invalid Python code or if the
+    /// formatter would otherwise write invalid Python code, then the code
+    /// example is ignored by the formatter and kept as-is.
+    ///
+    /// Currently, doctest, Markdown, reStructuredText literal blocks, and
+    /// reStructuredText code blocks are all supported and automatically
+    /// recognized.
+    #[option(
+        default = "false",
+        value_type = "bool",
+        example = r#"
+            # Enable reformatting of code snippets in docstrings.
+            docstring-code-format = true
+        "#
+    )]
+    pub docstring_code_format: Option<bool>,
+
+    /// Set the line length used when formatting code snippets in docstrings.
+    ///
+    /// This only has an effect when the `docstring-code-format` setting is
+    /// enabled.
+    ///
+    /// The default value for this setting is `"dynamic"`, which has the effect
+    /// of ensuring that any reformatted code examples in docstrings adhere to
+    /// the global line length configuration that is used for the surrounding
+    /// Python code. The point of this setting is that it takes the indentation
+    /// of the docstring into account when reformatting code examples.
+    ///
+    /// Alternatively, this can be set to a fixed integer, which will result
+    /// in the same line length limit being applied to all reformatted code
+    /// examples in docstrings. When set to a fixed integer, the indent of the
+    /// docstring is not taken into account. That is, this may result in lines
+    /// in the reformatted code example that exceed the globally configured
+    /// line length limit.
+    ///
+    /// For example, when this is set to `20` and `docstring-code-format` is
+    /// enabled, then this code:
+    ///
+    /// ```python
+    /// def f(x):
+    ///     '''
+    ///     Something about `f`. And an example:
+    ///
+    ///     .. code-block:: python
+    ///
+    ///         foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
+    ///     '''
+    ///     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:
+    ///
+    ///     .. code-block:: python
+    ///
+    ///         (
+    ///             foo,
+    ///             bar,
+    ///             quux,
+    ///         ) = this_is_a_long_line(
+    ///             lion,
+    ///             hippo,
+    ///             lemur,
+    ///             bear,
+    ///         )
+    ///     """
+    ///     pass
+    /// ```
+    #[option(
+        default = r#""dynamic""#,
+        value_type = r#"int | "dynamic""#,
+        example = r#"
+            # Format all docstring code snippets with a line length of 60.
+            docstring-code-line-length = 60
+        "#
+    )]
+    pub docstring_code_line_length: Option<DocstringCodeLineWidth>,
 }
 
 #[cfg(test)]

crates/ruff_workspace/src/settings.rs

@@ -5,7 +5,10 @@ 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, DocstringCodeLineWidth, MagicTrailingComma, PreviewMode, PyFormatOptions,
+    QuoteStyle,
+};
 use ruff_source_file::find_newline;
 use std::path::{Path, PathBuf};
 
@@ -124,6 +127,9 @@ pub struct FormatterSettings {
     pub magic_trailing_comma: MagicTrailingComma,
 
     pub line_ending: LineEnding,
+
+    pub docstring_code_format: DocstringCode,
+    pub docstring_code_line_width: DocstringCodeLineWidth,
 }
 
 impl FormatterSettings {
@@ -157,6 +163,8 @@ impl FormatterSettings {
             .with_preview(self.preview)
             .with_line_ending(line_ending)
             .with_line_width(self.line_width)
+            .with_docstring_code(self.docstring_code_format)
+            .with_docstring_code_line_width(self.docstring_code_line_width)
     }
 }
 
@@ -173,6 +181,8 @@ impl Default for FormatterSettings {
             indent_width: default_options.indent_width(),
             quote_style: default_options.quote_style(),
             magic_trailing_comma: default_options.magic_trailing_comma(),
+            docstring_code_format: default_options.docstring_code(),
+            docstring_code_line_width: default_options.docstring_code_line_width(),
         }
     }
 }