Use first paragraph instead of first line for method summary

[mwhudson]

There are cases where the summary doesn't fit in one line to be useful. An example would be

http://twistedmatrix.com/documents/11.0.0/api/twisted.application.service.ServiceMaker.html

The short summary in the green box for makeService().

I proposed a patch to mask the newline but exarkun refused it as he feels, it should be fixed inside of pydoctor so it works everywhere.

My idea would be to use the first paragraph instead of the first line for this summary and I'd also write a patch if others would support that idea.

---

Imported from Launchpad using lp2gh.

• date created: 2011-06-26T17:09:34Z
• owner: hyneks
• the launchpad url was https://bugs.launchpad.net/bugs/802223

[mwhudson]

(by mwhudson)
I think I generally agree, although there probably should be a limit of say three lines so that the summary doesn't get out of hand when people fail to follow the rules and start the docstring with a summary.

This shouldn't be hard, feel like writing a patch?

[mwhudson]

(by hyneks)
Sure. I'll look at it as soon as I get to my office.

[mwhudson]

(by hyneks)
I checked in a fix at http://bazaar.launchpad.net/~hyneks/pydoctor/summary-fix/revision/573 - let me know what you think.

I'm not sure what to make of pydoctor/html.py -- is that used somewhere?

(My first launchpad interaction, let me know if I'm doing something stupid.)

[mwhudson]

(by mwhudson)
html.py is mostly a relic of the formatter that existed before the nevow one (which should be redone to use twisted.web.template I guess) was written.

As to the branch, I wouldn't have used itertools so much but it works so I'll merge it :)

As to how to use launchpad, you seem to be doing fine! You could have used 'propose for merging' on your branch, but linking it from the bug report is good too.

[mwhudson]

(by hyneks)
Usually, I'm not much of an itertools snob neither, however this saved me two for loops and gave superior legibility so I just went for it. :)

I'm glad you like it, let me know if I can give you hand with something as long as I'm on a roll. ;)