line-spanning epytext markup generates an error

[Jean-Paul Calderone]

If some epytext markup with curlies spans multiple lines, pydoctor causes an epytext error to be emitted. However, using epydoc directly does not result in the same error, and epytext documentation suggests that spanning multiple lines is okay.

[Michael Hudson-Doyle (mwhudson)]

Ah. I think I know what's happening here: it's pydoctor's hackish way of extracting a summary line. For the table of contents, pydoctor takes the first non-blank line of ths docstring. In this case it's just "B{foo", which is unsurprisingly an error. It works fine for formatting the main docstring.

Not sure what to do about this.

[K Richard Pixley (rich-noir)]

Just ran into the same problem. Took a bit to track down what the problem actually is as the line numbers on the error message are useless.

Just knowing that it's the first line is helpful. I'd noticed truncation but hadn't yet twigged to it being the first line.

I can work around that.

[Michael Hudson-Doyle (mwhudson)]

Hm, the line numbers shouldn't be useless -- can you file a separate bug about that?

Ideas for better summary-extracting heuristics would be good. I think there is some mileage in taking the content up to the first blank line, unless that gets you more than say 200 characters, in which case you drop back to what we do know. Or you could try to do the truncation by processing the fully rendered complete docstring -- take the first paragraph level element or something. Or you could add some options to control this, but I don't really like this idea.

There's never going to be a clean answer for this.

[Michael Hudson-Doyle (mwhudson)]

I think the way pydoctor extracts summaries now is much less likely to hit this problem, so closing.