[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