Docstring parsing and formatting

[Ben Finney]

Howdy all,

Where can I find a standard implementation of the docstring parsing and
splitting algorithm from PEP 257?


PEP 257 describes a convention of structure and formatting for
docstrings <URL: http://www.python.org/dev/peps/pep-0257/>. Docstrings
that conform to this convention can therefore be parsed into their
component parts, and re-formatted.

The PEP describes <URL: http://www.python.org/dev/peps/pep-0257/#id20>
and algorithm for parsing the docstring as found in the string literal.
It says “Docstring processing tools will …” and goes on to describe, in
prose and example code, how the parsing should be done.

Where is a common implementation of that algorithm? It seems that it
should be in the Python standard library, but I can't find it.

Ideally what I want is to be able to write:

import textwrap

(summary, description) = textwrap.pep257_parse(foo.__doc__)

and have ‘summary’ as the docstring's summary line, and ‘description’ as
the docstring's description (as described in <URL:
http://www.python.org/dev/peps/pep-0257/#id19>).

[Terry Reedy]

On 9/17/2012 10:03 PM, Ben Finney wrote:
> Howdy all,
>
> Where can I find a standard implementation of the docstring parsing and
> splitting algorithm from PEP 257?

I presume there is something in the code behind help().

--
Terry Jan Reedy

[Joel Goldstick]

On Tue, Sep 18, 2012 at 1:03 AM, Terry Reedy <tjr...@udel.edu> wrote:
> On 9/17/2012 10:03 PM, Ben Finney wrote:
>>
>> Howdy all,
>>
>> Where can I find a standard implementation of the docstring parsing and
>> splitting algorithm from PEP 257?

Do you know about pydoc? I haven't looked at its source, but since it
does a great job of printing documentation from docstrings it might
contain what you need



--
Joel Goldstick

[Ben Finney]

Yes, I have now learned about the ‘pydoc’ module following the lead from
investigating the interactive interpreter's ‘help’ function
<URL:http://docs.python.org/library/pydoc.html>.

The ‘pydoc.splitdoc’ function, though not documented in the library
documentation, does what I need. It takes a docstring as input, and
returns a tuple of (synopsis, description).

Thanks to everyone who helped.

--
\ “Value your freedom or you will lose it, teaches history. |
`\ “Don't bother us with politics,” respond those who don't want |
_o__) to learn.” —Richard Stallman, 2002 |
Ben Finney