Gustaf Waldemarson wrote:
> I think that's a really good idea actually. It might also be a good idea to add a
> negative example (i.e., the black-indentation style you mentioned earlier), or
> a reference to one (maybe to the tests?)

I think the best way is to update the docstring of
`python-indent-def-block-scale'.  So, I am also CC'ing this mail to
the members of Bug#28475, where `python-indent-def-block-scale' was
introduced.

I made a separate patch to update the docstring of
`python-indent-def-block-scale'.  I think the name
`python-indent-def-block-scale' itself is a bit misleading, but I have
left it as is for compatibility.  The following is my proposal of the
docstring.  What do you think?

"Multiplier applied to indentation inside multi-line blocks.
The indentation in parens in the block header will be the current
indentation plus `python-indent-offset' multiplied by this
variable.  For example, the arguments are indented as follows if
this variable is 1:

    def do_something(
        arg1,
        arg2
    ):
        print('hello')

if this variable is 2 (default):

    def do_something(
            arg1,
            arg2):
        print('hello')

This variable has an effect on all blocks, not just def block.
This variable only works if the opening paren is not followed by
non-whitespace characters on the same line.  Modify
`python-indent-block-paren-deeper' to customize the case where
non-whitespace characters follow the opening paren on the same
line."