[Urwid] docgen_tutorial.py that also creates scripts

[Ian Ward]

Derek Peschel wrote:
> Here's a patch to docgen_tutorial.py that creates one .py file for each
> example.  While the "HTML screen shot" idea of the tutorial is very clever,
> there's no substitute for ordinary scripts that people can try out or change.
> The patch does some other things:

That's a very good idea.  One comment: the creation of the files and 
generation of documentation should be  command line options if the 
script is going to have two purposes.

> 
> For the scripts to be most useful, the examples in section 5 need to have
> main loops added.  The loops can be edited out of the HTML docs by adding more
> rules to cut_example_code.  I don't know enough of urwid's philosophy to
> write code that best illustrates the examples.  Section 5 should probably
> be rewritten anyway, because of the changes in 0.9.5 to make box and flow
> widgets more interchangeable.
> 
> Why is the example in section 3.1 so short?  It looks like an editing
> mistake to me.

WRT main loops in 5 and 3.1, maybe some kind of standard main loop 
should be introduced earlier and used through the rest of the examples.. 
I'm not sure. It's hard to write these things, and I probably know too 
much about Urwid to do a good job of it!  :-)

However, I don't agree that 0.9.5 makes section 5 obsolete. The only 
change I would make would be to improve the examples in 5.1 now that you 
can make almost anything by WidgetWrap-ing Columns and Pile widgets. 
Which reminds me, section 4 really needs some examples.

> 
> I wanted the file names to have section numbers instead of internal tag
> names, but I don't know how to do that.  I've only tested the patch on
> Mac OS X.  Even then, the generated files aren't made executable.  So there's
> more work to do, but this is a start.


The files could be numbered the same way that the numbers are generated 
for the table of contents.