-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Description
In #8811, the formatter grew the ability to format doctest code snippets in docstrings. In this initial implementation, it handles line width limits by resetting the column of the code snippet to the first column. It is unclear whether this is the right behavior. This means that individual lines inside the docstring can exceed line length limits imposed by the linter, and it also just generally means that it is difficult to maintain a line length limit in the source code.
The benefit of the current behavior is that it prioritizes the presentation of the code snippet itself. So that when a documentation generator renders a code snippet, its presented line length will be correct with respect to the project's configured line limits.
The downside of the current behavior is that the source code itself can have long lines. (This would be quite annoying to me personally, perhaps enough to eclipse the benefit of the presentation having a correct line length.)
Here are a few options we can pursue:
- We could leave the existing behavior as-is and provide no configuration.
- We could add a new option,
docstring-code-line-width, that lets one configure the line width of code snippets independent of the line width of the surrounding code. - We could add a new option,
docstring-code-preserve-line-widththat dynamically chooses the line width of a reformatted code snippet based on the column at which in starts within the source code and the globally configured line width. - Do (2) and (3).
Maybe there are other choices. Speaking for myself personally, if I were to use code snippet formatting, I would want option (3) because it preserves the line length limit correctly regardless of the indentation of the docstring. I'm not sure I would add option (2) at all.