Skip to content

Commit

Permalink
config: add new 'docstring-code' knob
Browse files Browse the repository at this point in the history
This commit does the plumbing to make a new formatting option,
'docstring-code', 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.
  • Loading branch information
BurntSushi committed Nov 27, 2023
1 parent d9845a2 commit 1a75fdd
Show file tree
Hide file tree
Showing 4 changed files with 70 additions and 2 deletions.
14 changes: 13 additions & 1 deletion crates/ruff_workspace/src/configuration.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -180,6 +180,9 @@ impl Configuration {
magic_trailing_comma: format
.magic_trailing_comma
.unwrap_or(format_defaults.magic_trailing_comma),
docstring_code: format
.docstring_code
.unwrap_or(format_defaults.docstring_code),
};

let lint = self.lint;
Expand Down Expand Up @@ -1011,6 +1014,7 @@ pub struct FormatConfiguration {
pub quote_style: Option<QuoteStyle>,
pub magic_trailing_comma: Option<MagicTrailingComma>,
pub line_ending: Option<LineEnding>,
pub docstring_code: Option<DocstringCode>,
}

impl FormatConfiguration {
Expand All @@ -1037,6 +1041,13 @@ impl FormatConfiguration {
}
}),
line_ending: options.line_ending,
docstring_code: options.docstring_code.map(|yes| {
if yes {
DocstringCode::Enabled
} else {
DocstringCode::Disabled
}
}),
})
}

Expand All @@ -1050,6 +1061,7 @@ 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: self.docstring_code.or(other.docstring_code),
}
}
}
Expand Down
43 changes: 43 additions & 0 deletions crates/ruff_workspace/src/options.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2835,6 +2835,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.
docstring-code = true
"#
)]
pub docstring_code: Option<bool>,
}

#[cfg(test)]
Expand Down
8 changes: 7 additions & 1 deletion crates/ruff_workspace/src/settings.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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};

Expand Down Expand Up @@ -124,6 +126,8 @@ pub struct FormatterSettings {
pub magic_trailing_comma: MagicTrailingComma,

pub line_ending: LineEnding,

pub docstring_code: DocstringCode,
}

impl FormatterSettings {
Expand Down Expand Up @@ -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.docstring_code)
}
}

Expand All @@ -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(),
docstring_code: default_options.docstring_code(),
}
}
}
Expand Down
7 changes: 7 additions & 0 deletions ruff.schema.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit 1a75fdd

Please sign in to comment.