[Twisted-Python] Why is this epytext docstring bad?

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Tue Apr 9 09:00:57 EDT 2013


On 12:02 pm, _ at lvh.cc wrote:
>Hi,
>
>I'm trying to get twisted.positioning landed, but it's blocking on an
>invalid epytext docstring. I've stared at this docstring a few times in 
>the
>past weeks, but that didn't help.
>
>Failing buildbot log:
>https://buildbot.twistedmatrix.com/builders/documentation/builds/3141/steps 
>/api-documentation/logs/stdio
>
>Docstring:
>https://twistedmatrix.com/trac/browser/branches/positioning-3926-2/twisted/positioning/nmea.py?rev=37997#L256
>
>If someone could tell me what's wrong with it, that'd be much 
>appreciated :)

Here's how you can find out what's wrong with an epytext docstring:

    >>> from epydoc.markup.epytext import parse_docstring
    >>> from twisted.positioning.nmea import NMEASentence
    >>> errors = []
    >>> parse_docstring(NMEASentence.__doc__, errors)
    >>> errors
    [<ParseError on line 70>, <ParseError on line 73>, ...]
    >>> print errors[0]
    Line 70: Possible mal-formatted field item.
    >>>

In this particular case, I think a lot of the errors are caused by 
interleaving "fields" (epytext calls things that start with "@" 
"fields") with prose.  My understanding of the rules are that prose must 
come first and fields must come last.  The epytext documentation seems 
to bear this out:

    Fields must be placed at the end of the docstring, after the
    description of the object. Fields may be included in any order.

from http://epydoc.sourceforge.net/epytext.html

Jean-Paul



More information about the Twisted-Python mailing list