Added "Handling Docstring Indentation" section.

pep-0257.txt

@@ -136,15 +136,9 @@ docstring, followed by a blank line, followed by a more elaborate
 description.  The summary line may be used by automatic indexing
 tools; it is important that it fits on one line and is separated from
 the rest of the docstring by a blank line.  The summary line may be on
-the same line as the opening quotes or on the next line.
-
-The entire docstring is indented the same as the quotes at its first
-line (see example below).  Docstring processing tools will strip a
-uniform amount of indentation from the second and further lines of the
-docstring, equal to the minimum indentation of all non-blank lines
-after the first line of the docstring.  Relative indentation of later
-lines in the docstring is retained.  Any indentation on the first line
-of the docstring (i.e., before the first newline) is removed.
+the same line as the opening quotes or on the next line.  The entire
+docstring is indented the same as the quotes at its first line (see
+example below).
 
 Insert a blank line before and after all docstrings (one-line or
 multi-line) that document a class -- generally speaking, the class's
@@ -218,6 +212,76 @@ the closing quotes on a line by themselves.  This way, Emacs'
 ``fill-paragraph`` command can be used on it.
 
 
+Handling Docstring Indentation
+------------------------------
+
+Docstring processing tools will strip a uniform amount of indentation
+from the second and further lines of the docstring, equal to the
+minimum indentation of all non-blank lines after the first line.  Any
+indentation in the first line of the docstring (i.e., up to the first
+newline) is insignificant and removed.  Relative indentation of later
+lines in the docstring is retained.  Blank lines should be removed
+from the beginning and end of the docstring.
+
+Since code is much more precise than words, here is an implementation
+of the algorithm::
+
+    def trim(docstring):
+        if not docstring:
+            return ''
+        # Convert tabs to spaces (following the normal Python rules)
+        # and split into a list of lines:
+        lines = docstring.expandtabs().splitlines()
+        # Determine minimum indentation (first line doesn't count):
+        indent = sys.maxint
+        for line in lines[1:]:
+            stripped = line.lstrip()
+            if stripped:
+                indent = min(indent, len(line) - len(stripped))
+        # Remove indentation (first line is special):
+        trimmed = [lines[0].strip()]
+        if indent < sys.maxint:
+            for line in lines[1:]:
+                trimmed.append(line[indent:].rstrip())
+        # Strip off trailing and leading blank lines:
+        while trimmed and not trimmed[-1]:
+            trimmed.pop()
+        while trimmed and not trimmed[0]:
+            trimmed.pop(0)
+        # Return a single string:
+        return '\n'.join(trimmed)
+
+The docstring in this example contains two newline characters and is
+therefore 3 lines long.  The first and last lines are blank::
+
+    def foo():
+        """
+        This is the second line of the docstring.
+        """
+
+To illustrate::
+
+    >>> print repr(foo.__doc__)
+    '\n    This is the second line of the docstring.\n    '
+    >>> foo.__doc__.splitlines()
+    ['', '    This is the second line of the docstring.', '    ']
+    >>> trim(foo.__doc__)
+    'This is the second line of the docstring.'
+
+Once trimmed, these docstrings are equivalent::
+
+    def foo():
+        """A multi-line
+        docstring.
+        """
+
+    def bar():
+        """
+        A multi-line
+        docstring.
+        """
+
+
 References and Footnotes
 ========================