Black reforms Click docstring use "prevent rewrapping" controls

[jeremyschulman]

Describe the bug

As a Developer using the Click library, I often use the docstring formatting control character slash-b and slash-f as described here: https://click.palletsprojects.com/en/8.0.x/documentation/#preventing-rewrapping

When I use black to reform my code, black will "right shift" the content in an unexpected and undesired manner.

To Reproduce

Create a Click command using the control formatting:

def cli_design_report_interfaces(devices: Tuple[str], **flags):
    """
    report device interfaces usage

\b
    The output includes the interface name, description, assigned profile, and
    physical port type.  By default this command will show only interfaces that
    are used in the design.  Any unused interfaces will be omitted.  Additonal
    flag options:
       --all : show the unused interfaces
       --unused : show only the unused interfaces

\f
    Parameters
    ----------
    devices: tuple[str]
        A tuple of device names provided by the User
    """

Run black. Observe the reformatted/indented text:

def cli_design_report_interfaces(devices: Tuple[str], **flags):
    """
        report device interfaces usage

    \b
        The output includes the interface name, description, assigned profile, and
        physical port type.  By default this command will show only interfaces that
        are used in the design.  Any unused interfaces will be omitted.  Additonal
        flag options:
           --all : show the unused interfaces
           --unused : show only the unused interfaces
    \f
        Parameters
        ----------
        devices: tuple[str]
            A tuple of device names provided by the User
    """

IF, however, the formatting controls are aligned differently, then black DOES NOT reformat the string. For example:

def cli_design_report_interfaces(devices: Tuple[str], **flags):
    """
    report device interfaces usage

    \b
    The output includes the interface name, description, assigned profile, and
    physical port type.  By default this command will show only interfaces that
    are used in the design.  Any unused interfaces will be omitted.  Additonal
    flag options:
       --all : show the unused interfaces
       --unused : show only the unused interfaces

    \f
    Parameters
    ----------
    devices: tuple[str]
        A tuple of device names provided by the User
    """

Expected behavior

black should not "right-shift" the text

Environment (please complete the following information):

• Version: black, version 21.9b0
• OS and Python version: MacOS Catalina (10.15.7). Python 3.8.10

[HassanAbouelela]

I know that docstrings are a bit controversial here, but the indentation behavior I think is correct. PEP8 (PEP257 actually) has the following to say:

The entire docstring is indented the same as the quotes at its first line

[HassanAbouelela]

To more directly address your desired style, I feel like that would take away from a user’s ability to do indentation should they need it, which I believe is also valid under PEP. It’s possible for you to achieve the desired style right now, without taking that ability away. If black had to make that decision itself, it’d be more complicated.

[jeremyschulman]

@HassanAbouelela - thank you for your follow-up. I understand your explanation and agree with your reasoning. I will need to be diligent in the placement of my control-characters so that the doctoring aligns to the PEP257.

Closing this issue.