Deprecate twisted.python.text.docstringLStrip

[thijs]

No other code in Twisted uses this method and it hasn't been touched in 6 years;

"""Gets rid of unsightly lefthand docstring whitespace residue.

    You'd think someone would have done this already, but apparently
    not in 1.5.2.

    BUT since we're all using Python 2.1 now, use L{inspect.getdoc}
    instead.  I{This function should go away soon.}
    """

[exarkun]

Deprecate it first, of course.

[cyli]

(In [29347]) Branching to 'deprecate-docstringLStrip-4328'

[cyli]

(In [29354]) Deprecate twisted.python.text.docstringLStrip.

refs #4328

[cyli]

(In [29355]) Ensure that flushWarnings only flushes the warnings dealing with this particular deprecation case.

refs #4328

[thijs]

please remove the usage of L{} in the deprecation message because its not touched by epydoc afaik.

[thijs]

the ref to python (2.1) should also go or be put into todays context.

[cyli]

(In [29406]) Removed the L{} from deprecation messages, and deprecate as of 10.2 instead of 10.1

refs #4328

[cyli]

In regards to changing the docstringLStrip docstring, I think it should be left as is - it dates the method. Also, since it's going to be removed anyway, we probably shouldn't give the impression that we are still maintaining/modifying that method by updating the docstring.

[exarkun]

Looks good to me. Please merge, assuming the  build results look good.

[cyli]

(In [29448]) Merge deprecate-docstringLStrip-4328 : Deprecate t.p.text.docstringLStrip

Author: cyli Reviewer: thjis, exarkun Fixes: #4328

Deprecate twisted.python.text.docstringLStrip

[thijs]

#5036 will remove it.