[RFC][PATCH] testable api documentation

[John Arbash Meinel]

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?

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"

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.

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)

John
=:->

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060129/207b088c/attachment.pgp