ruff_python_formatter: add docstring-code-line-width internal setting #9055
Conversation
BurntSushi
added
internal
This permits setting a line width for code examples in docstrings that is distinct from the line width of the surrounding Python code. Its default is the same as for Python: 88. But note that changing the line width for the surrounding Python code does not also change it for docstring code examples. They are configured separately. Note that I chose "width" for this internal option to make it consistent with other internal options, even though it seems like we would like to eventually use the word "length" to match public facing documentation.
BurntSushi
force-pushed
the
ag/fmt/line-length
branch
from
f87c42a
to
d6e2762
Compare
This adds the new docstring-code-line-width setting to the snapshot output.
This applies the changes from the previous commit. We split it out into a distinct commit to make review a little easier.
We add a new configuration with a docstring line width, but specifically keep it at the default for now to make review changes based on line width easier. In the next commit, will add changes to the snapshot. In the commit following that, we'll finally change the actual line width setting and we'll be able to see precisely its impact.
This is the test output from the previous commit, where we set the docstring code line width explicitly, but to the default. The next commit will change the line width to a non-default setting.
This updates the line width setting and the test output. Since most of our tests use very short lines, the chnages are small. They look like what I'd expect. Ref #8855
BurntSushi
force-pushed
the
ag/fmt/line-length
branch
from
d6e2762
to
1f021fb
Compare
|
| /// docstring code examples. This only has an impact when `docstring_code` | ||
| /// is enabled. | ||
| #[cfg_attr(feature = "serde", serde(default = "default_line_width"))] | ||
| docstring_code_line_width: LineWidth, |
There was a problem hiding this comment.
I'd expect this to default to the formatter's line-length, but I think that happens at a level above, when we create the Settings.
There was a problem hiding this comment.
Good point. I don't know if serde supports defaults that depend on another field's value.
There was a problem hiding this comment.
I specifically didn't attempt this, because this would imply a same-as-global setting which is distinct from a specific fixed integer. I think that if we do want that mode, then we ought to make it an explicit setting so that users can specifically opt into it in other contexts. So for example, instead of using LineWidth here, I'd do:
enum DocstringCodeLineWidth {
SameAsGlobal,
Fixed(LineWidth),
}And then hopefully we'll add Dynamic (pending my experimentation today).
But we can also hash this out a bit more when I add the user-facing version of this.
Summary
This does the light plumbing necessary to add a new internal option that permits setting the line width of code examples in docstrings. The plan is to add the corresponding user facing knob in #8854.
Note that this effectively removes the
same-as-globalconfiguration style discussed in this comment. It replaces it with the{integer}configuration style only.There are a lot of commits here, but they are each tiny to make review easier because of the changes to snapshots.
Test Plan
I added a new docstring test configuration that sets
docstring-code-line-width = 60and examined the differences.