ruff_python_formatter: add docstring-code-line-width internal setting#9055
Merged
BurntSushi merged 6 commits intomainfrom Dec 11, 2023
Merged
ruff_python_formatter: add docstring-code-line-width internal setting#9055BurntSushi merged 6 commits intomainfrom
BurntSushi merged 6 commits intomainfrom
Conversation
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.
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
d6e2762 to
1f021fb
Compare
Contributor
|
| /// 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, |
Member
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.
Member
There was a problem hiding this comment.
Good point. I don't know if serde supports defaults that depend on another field's value.
Member
Author
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.
charliermarsh
approved these changes
Dec 8, 2023
MichaReiser
approved these changes
Dec 10, 2023
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.