[Doc-SIG] Some random thoughts

[Ka-Ping Yee]

On Sun, 5 Mar 2000, Laurence Tratt wrote:
> Here are some things that tend to cause complications in current doc
> strings:
> 
>   * Many look like:
> 
>     def __init__(self):
>     """The first line
> 
>        The rest of the body
> 
>        Blah blah
>     """
> 
>     What exactly is the indentation of that whole thing? To the human eye
>       the answer is 8. In my implementation the above *doesn't* do what you
>       expect because the first line gets an indentation of 0 and the rest
>       an indentation of 8 (meaning the body is a sub paragraph of the rest):

I came across this problem too.  "manpy"'s solution to this problem
is to look for the minimum indentation of all lines except the first,
and remove that amount of indentation from all the lines in the string.

More compactly stated,

    lines = split(expandtabs(docstring), "\n")
    margin = min(map(lambda line: len(line) - len(lstrip(line)), lines[1:]))
    for i in range(1, len(lines)): lines[i] = lines[i][margin:]

It does make assumptions, but it's always done the right thing so far.


-- ?!ng

"To be human is to continually change.  Your desire to remain as you are
is what ultimately limits you."
    -- The Puppet Master, Ghost in the Shell