problematic formatting: indentation change in docstring

[kaddkaka]

black and ruff format might destroy ascii art in dosctring when re-indenting docstring lines. (so I'm not sure if this issue should be filed here or at the black project)

Example code:

def dosctring_ascii_alignment():
    """Ascii art: [____,aaaa,bbbb]
                   ^         ^
    """
    pass

result after ruff format (with version 0.3.2):

def dosctring_ascii_alignment():
    """Ascii art: [____,aaaa,bbbb]
    ^         ^
    """
    pass

as seen, the carets ^ are now misaligned.

In my mind it would be better to not touch docstrings - but I guess there might be some reason for it?

[ilius]

I would totally agree.
Docstrings are just strings that happen to be the first expression in the function / class.
Formatter would not normally modify strings.
As the Zen of Python says: "Special cases aren't special enough to break the rules."

What benefit does it have to justify it?

[charliermarsh]

Ah yeah, I'd suggest just disabling formatting for the docstring in this case.

On a whole, it is a net positive (by far, in my opinion) for the formatter to correct docstring indentation than to disable it entirely due to special cases like (e.g.) ASCII art. You are of course welcome to file an issue with Black if you'd like.

[ilius]

Oh I didn't know there was am option to disable it thanks!

docstring-code-format = false

https://github.com/astral-sh/ruff/blob/main/docs/formatter.md
https://github.com/astral-sh/ruff/blob/main/docs/configuration.md

BTW: there are a few parameters missing in docs/formatter.md.
Should I add them as PR?

[zanieb]

To avoid confusion.. docstring-code-format is for code blocks in docstrings, not the docstrings themselves. You're probably looking to just use # fmt: skip

def foo():
    """
        test
    """  # fmt: skip

I'm not sure it's worth enumerating all configuration options in the formatter overview but feel free to pull request anything you think would be helpful and we can discuss it there.

[kaddkaka]

#fmt is not really an option since I would have to look over thousands of docstring to try and find where to add that waiver.

Breaking information like this is not good and cane in the worst case be very confusing/misleading.

Ruff already has some options that black does not, but I might open a PR on black side then.

[kaddkaka]

The ruff source code seems to try and keep indentation alignment in some cases, for example this code is formatted according to ruff:

def dosctring_ascii_alignment():
    """Ascii art: [____,aaaa,bbbb]
    ^         ^
    """
    pass


def dosctring_ascii_alignment():
    """
    Ascii art: [____,aaaa,bbbb]
                     ^^^^
    """

As seen in the 2nd function, the docstring is not modified.