This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Enhance Cmd support for docstrings and document it.
Type: enhancement Stage: patch review
Components: Library (Lib) Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: daniel.urban, eric.araujo, r.david.murray, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2010-02-11 18:57 by r.david.murray, last changed 2022-04-11 14:56 by admin.

Files
File name Uploaded Description Edit
cmd_doctest_enhancement.patch r.david.murray, 2010-02-11 18:57
Messages (7)
msg99233 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-02-11 18:57
Cmd currently has undocumented support for using the docstrings of 'do_' methods as the documentation for those methods.  This is a very convenient facility, except that it leads to documentation being printed with a lot of leading whitespace.

I propose to enhance the docstring support to strip the leading whitespace from the docstring, and to document this facility.  The proposed stripping algorithm is to strip a number of characters equal to the whitespace on the first non-blank line of the docstring.  This means that existing docstrings, which will typically start right after the first """, will be displayed as they were previously, but that a docstring can be formatted by starting the documentation on a new line after the """, and whitespace will be properly stripped.

Patch attached with test and documentation update.
msg101837 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-03-27 18:33
Hello

This would be a nice improvement. This weakness is indeed mentioned on PyMotW.

How about using textwrap.dedent?

Regards
msg101843 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-03-27 19:09
The problem with using textwrap is that you'd have to identify paragraph boundaries and example code to avoid messing up the meaning of the doc string.  At that point, one might as well go for full ReST markup parsing, and I don't think that is appropriate :)
msg101844 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-03-27 19:23
> The problem with using textwrap is that you'd have to identify paragraph boundaries
> and example code to avoid messing up the meaning of the doc string.

I thought dedent just worked. Can you provide a simple example to help 
me understand this problem?

Does this help:
http://code.activestate.com/recipes/358228-extend-textwraptextwrapper-to-handle-multiple-para/

Regards
msg131485 - (view) Author: Daniel Urban (daniel.urban) * (Python triager) Date: 2011-03-20 11:51
inspect.cleandoc (which is also used by inspect.getdoc and pydoc.getdoc) seems to do a similar thing.  Maybe that could be used for this?
msg131502 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-20 15:50
You can apply the patch (which includes tests) and edit the code of cmd.py to use cleandoc.
msg290520 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-03-26 10:12
Can you create a pull request David?
History
Date User Action Args
2022-04-11 14:56:57adminsetgithub: 52161
2017-03-26 10:12:56serhiy.storchakasetnosy: + serhiy.storchaka

messages: + msg290520
versions: + Python 3.7, - Python 3.3
2011-03-20 15:50:31eric.araujosetmessages: + msg131502
versions: + Python 3.3, - Python 3.2
2011-03-20 11:51:56daniel.urbansetnosy: + daniel.urban
messages: + msg131485
2010-03-27 19:24:00eric.araujosetmessages: + msg101844
2010-03-27 19:09:58r.david.murraysetmessages: + msg101843
2010-03-27 18:33:11eric.araujosetnosy: + eric.araujo
messages: + msg101837
2010-02-11 18:57:20r.david.murraycreate