launchpad-dev team mailing list archive

[Jonathan Lange <jml@xxxxxxxxxxxxx>]

On Wed, Dec 9, 2009 at 9:29 PM, Bjorn Tillenius <bjorn@xxxxxxxxxxxxx> wrote:
> On Mon, Dec 07, 2009 at 09:57:28AM +1100, Jonathan Lange wrote:
>> On Thu, Dec 3, 2009 at 10:15 AM, Bjorn Tillenius <bjorn@xxxxxxxxxxxxx> wrote:
>> > It should be documentation with tests. It would probably be
>> > possible to have a normal unittest test, exctract the comments, and
>> > produce a suitable document.
>> >
>>
>> It is! See https://launchpad.net/testdoc for a tool that does exactly this.
>
> Yeah, I knew about that, actually. Do you have an example (preferably in
> the LP tree) of where this is used successfully? I.e., where the
> comments from a Python unittest test produce a nice and readable
> document.

I don't use testdoc in my day to day development, mostly because it's
not integrated with our current toolchain, there's no where to put the
docs it generates, and no one would read them anyway.

But, I grabbed a copy of testdoc, ran it on
lp.code.model.test.test_branchcollection. Here's what it generated:
http://pastebin.ubuntu.com/339043/

Some thoughts:
 * It's a very different type of document to a doctest -- more a
collection of small specifications than a tutorial.
 * If testdoc were part of my development process, I know I'd have
written some of those comments differently.
 * There are some actual bugs in the documentation generation.
 * I'm surprised it worked so well after three years of not actually being used.

jml