[RFC][PATCH] testable api documentation

[Robert Collins]

On Sun, 2006-01-29 at 09:59 -0600, John Arbash Meinel wrote:
> Robert Collins wrote:
> > On Sun, 2006-01-29 at 21:49 +1100, Robert Collins wrote:
> >> This documentation is for end users of the api. Its testable so that it
> >> wont bitrot. At this point its pure python, and I think that that is the
> >> way it should stay - as its about demonstrating the api from within
> >> python, so its appropriate to show every step as python.
> >>
> >> Seeking a +1 to merge to mainline.
> > 
> > Oh yeah, http://people.ubuntu.com/~robertc/baz2.0/test-apis
> > 
> > Rob
> 
> So this is basically an extension of your other email, where we want to
> write testable documentation, is that correct?

Well, this branch predates it, but yes they are related.

> I like the idea, though I think we could modify the ReST parser, to use
> extensions. So you do something like:
> 
> .. unittest::
> 
>   >>> somepythoncode
> 
> .. unittest-with-sftp::
> 
>   >>> some more python code
> 
> etc.
> 
> I don't remember exactly how you install extra extensions into ReST, but
> I know that it is possible.
> 
> Actually if you did it right, you could even make it look nicer for people:
> 
> .. py-unit-test::
> 
>    import bzrlib.transport
>    t = bzrlib.transport.get()
> 
> And then you make the documentation writer just export this as standard
> block text, as though you did
> 
> ::
> 
>    import bzrlib.transport
>    t = bzrlib.transport.get()
> 
> And you could do the same for:
> 
> .. cmd-line-unit-test:
> 
>    bzr init
>    bzr commit -m "foo"

Well, I think the source files should be what we should as txt
documentation, though exports to html etc should be possible. I'm not
sure about the semi magic blocks above ..

> We can use the $ and the >>> if you want, but I do think the above can
> look nicer. I'm not exactly sure how you test the results. So it might
> be better to use DocTest.

DocTest uses the >>> for python code.  The $ is meant to look like a
shell prompt, as a no-explanations-needed format.

> But in the mean time, what you have written looks good. So +1 to merge
> it. I have it in jam-integration now. (revno 1514)

Thanks,
Rob
-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060130/8c504817/attachment.pgp