Using ruff to format code examples in docstrings

[stinodego]

At @pola-rs , we currently use ruff in combination with black for our Python formatting needs. We also use blackdoc for formatting our docstring code examples. Out of these three, blackdoc is by far the slowest.

With ruff gaining many of the capabilities of the black formatter, it would be great if we could also replace blackdoc soon and only use ruff.

[MichaReiser]

This sounds really useful and something our formatter could do. However, I don't expect us to make progress on this in the near future but happy to talk external contributors through on how this could be implemented.

One question that comes to mind is what do with code that has syntax errors but the easiest is to just leave such code unchanged.

[stinodego]

This sounds really useful and something our formatter could do. However, I don't expect us to make progress on this in the near future but happy to talk external contributors through on how this could be implemented.

Without any knowledge of the code base:

I think Examples blocks can already be detected as there are some docstring formatting rules in pydocstyle related to sections.
Then within the block, code examples should be easy to detect as lines starting with >>> , followed by one or more lines starting with ... . Example:

>>> pl.date_range(
...     date(2023, 1, 1), date(2023, 5, 1), "1mo", eager=True
... ).dt.month_end()

You'll probably find more refined logic by looking at the blackdoc source code, though.

One question that comes to mind is what do with code that has syntax errors but the easiest is to just leave such code unchanged.

I would imagine code examples with syntax errors raise an error, and would lead to that specific example to not be autofixed.

[MichaReiser]

I think Examples blocks can already be detected as there are some docstring formatting rules in pydocstyle related to sections.

I guess this brings up the question whether this should be a lint rule with an autofix or integrated into the formatter (runs automatically on save)? I assumed that this would be similar to the linked project and be part of the formatter.

The big challenge will be to implement fast parsing and integrate it in the otherwise already extensive docstring formatting

ruff/crates/ruff_python_formatter/src/expression/string.rs

Lines 787 to 905 in c05e462

	fn format_docstring(string_part: &FormatStringPart, f: &mut PyFormatter) -> FormatResult<()> {
	let locator = f.context().locator();
	// Black doesn't change the indentation of docstrings that contain an escaped newline
	if locator.slice(string_part).contains("\\\n") {
	return string_part.fmt(f);
	}
	let (normalized, _) = normalize_string(
	locator.slice(string_part),
	string_part.preferred_quotes,
	string_part.is_raw_string,
	);
	// is_borrowed is unstable :/
	let already_normalized = matches!(normalized, Cow::Borrowed(_));
	let mut lines = normalized.lines().peekable();
	// Start the string
	write!(
	f,
	[
	source_position(string_part.start()),
	string_part.prefix,
	string_part.preferred_quotes
	]
	)?;
	// We track where in the source docstring we are (in source code byte offsets)
	let mut offset = string_part.start();
	// The first line directly after the opening quotes has different rules than the rest, mainly
	// that we remove all leading whitespace as there's no indentation
	let first = lines.next().unwrap_or_default();
	// Black trims whitespace using [`str.strip()`](https://docs.python.org/3/library/stdtypes.html#str.strip)
	// https://github.com/psf/black/blob/b4dca26c7d93f930bbd5a7b552807370b60d4298/src/black/strings.py#L77-L85
	// So we use the unicode whitespace definition through `trim_{start,end}` instead of the python
	// tokenizer whitespace definition in `trim_whitespace_{start,end}`.
	let trim_end = first.trim_end();
	let trim_both = trim_end.trim_start();
	// Edge case: The first line is `""" "content`, so we need to insert chaperone space that keep
	// inner quotes and closing quotes from getting to close to avoid `""""content`
	if trim_both.starts_with(string_part.preferred_quotes.style.as_char()) {
	space().fmt(f)?;
	}
	if !trim_end.is_empty() {
	// For the first line of the docstring we strip the leading and trailing whitespace, e.g.
	// `""" content ` to `"""content`
	let leading_whitespace = trim_end.text_len() - trim_both.text_len();
	let trimmed_line_range =
	TextRange::at(offset, trim_end.text_len()).add_start(leading_whitespace);
	if already_normalized {
	source_text_slice(trimmed_line_range, ContainsNewlines::No).fmt(f)?;
	} else {
	text(trim_both, Some(trimmed_line_range.start())).fmt(f)?;
	}
	}
	offset += first.text_len();
	// Check if we have a single line (or empty) docstring
	if normalized[first.len()..].trim().is_empty() {
	// For `"""\n"""` or other whitespace between the quotes, black keeps a single whitespace,
	// but `""""""` doesn't get one inserted.
	if needs_chaperone_space(string_part, trim_end)
	|| (trim_end.is_empty() && !normalized.is_empty())
	{
	space().fmt(f)?;
	}
	string_part.preferred_quotes.fmt(f)?;
	return Ok(());
	}
	hard_line_break().fmt(f)?;
	// We know that the normalized string has \n line endings
	offset += "\n".text_len();
	// If some line of the docstring is less indented than the function body, we pad all lines to
	// align it with the docstring statement. Conversely, if all lines are over-indented, we strip
	// the extra indentation. We call this stripped indentation since it's relative to the block
	// indent printer-made indentation.
	let stripped_indentation = lines
	.clone()
	// We don't want to count whitespace-only lines as miss-indented
	.filter(|line| !line.trim().is_empty())
	.map(|line| count_indentation_like_black(line, f.options().tab_width()))
	.min()
	.unwrap_or_default();
	while let Some(line) = lines.next() {
	let is_last = lines.peek().is_none();
	format_docstring_line(
	line,
	is_last,
	offset,
	stripped_indentation,
	already_normalized,
	f,
	)?;
	// We know that the normalized string has \n line endings
	offset += line.text_len() + "\n".text_len();
	}
	// Same special case in the last line as for the first line
	let trim_end = normalized
	.as_ref()
	.trim_end_matches(|c: char| c.is_whitespace() && c != '\n');
	if needs_chaperone_space(string_part, trim_end) {
	space().fmt(f)?;
	}
	write!(
	f,
	[
	string_part.preferred_quotes,
	source_position(string_part.end())
	]
	)
	}

I would imagine code examples with syntax errors raise an error, and would lead to that specific example to not be autofixed.

That's my intuition but the question is would the rest of the file still be formatted? I would say yes, but the formatter then needs a way to raise a warning which we lack today.

[stinodego]

I guess this brings up the question whether this should be a lint rule with an autofix or integrated into the formatter (runs automatically on save)?

I would imagine this would have to be part of the autoformatter.

That's my intuition but the question is would the rest of the file still be formatted?

Yes, definitely. Other code examples in the same docstring could probably still be formatted, even. Each example is a self-contained Python interpreter command.

[BurntSushi]

@stinodego Out of curiosity, was there anything that pushed you to use blackdoc instead of blacken-docs? Also, do you use blackdoc to only reformat Python code in doc comments, or do you also use it to reformat Python code in other files (like, say, a README.rst or README.md)?

[stinodego]

I didn't pick blackdoc myself, it was introduced to the project at some point by someone else and I never thought to try other tools. I had heard of blacken-docs but have never tried it myself. It seems to do more than I need.

We currently only format Python in docstring examples. We don't autoformat code in our README, and code in our other docs is magically imported from Python files, so we can use ruff autoformatter for those.