[RFC] testable tutorial / doctests for ui

[Robert Collins]

Hi,
	I dont recall if this has been discussed on list or not, but it has
certainly been discussed a little here n there.

There are two related concepts:
 * Making the example commands in the tutorial be tested during test
suite runs, so that its always current and accurate.
 * Making it easier to write CLI tests by providing an extension of the
doctest parser that understands bzr commands.

So to do this, someone needs to write up a doctest parser, and a
supporting emulation of cwd etc.

Seems to me that if we agree on what the syntax to be used in such tests
is, someone can write the parser etc. :)..

So, I propose the following:

I'd like to allow the use of python in the tests, for when we need to
get down and dirty - and it would be useful in some parts of the
tutorial too I suspect. (I.e. if we have a tutorial on using the
library).

So all the doctest features would apply:
===
ReST here::

  >>> python code here

And we then add shell like syntax
  
  $ bzr commit -m "'example unicode cömmit'"

Note the literal small o with diaeresis :).
===

I think we do need proper quoting support, if only so that writing the
tutorial or tests is not surprising.

Each script file will need to get a private working directory for these
bzr commands to operate in - and probably we want them to have an sftp
and http server available as needed - but thats a separate issue as we
can start without that level of flexability.

Needed commands ? I think the shell commands we need to emulate to make
for useful demonstration texts are:

cd
mkdir & rmdir
touch (not core, but handy)
cat
echo (i.e. echo "content A" > foo.txt)
rm (including -rf)
ls (maybe with -a, should not need -l)
ln -s (hardlinks not needed)


I think thats enough for us to start with - if we need more we can add
them (well duh).

At this ppoint, I'm seeking +1's on the concept and the proposal, not on
code.

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/20060129/503fe0b3/attachment.pgp