ianb at colorstudy.com
Tue Oct 23 07:45:35 CEST 2007
Guido van Rossum wrote:
> 2007/10/22, Ian Bicking <ianb at colorstudy.com>:
>>> I briefly looked at the tutorial and was put off a little by the
>>> interactive prompt style of the examples; that seems so unrealistic
>>> that I wonder if it wouldn't be better to just say "put this in a file
>>> and run it like this"?
>> The side effect of doctesting is that docs sometimes look weird :-/
> Personally, I find doctest a great tool for writing tests in certain
> situations; not so great for writing docs though.
Yeah... I really like it in a lot of ways, but I'm not quite sure what
the right balance is. Untested documentation is also very unfortunate;
too much potential for drift.
>> I'm not sure what form the docs should take. I'm open to suggestions.
>> The extracted docs are actually reasonable as a reference, I think:
> Hm, these are mostly alphabetical listings of individual methods and
> properties. I'm still hoping for something that I can read from top to
> bottom in 10 minutes and get an idea of what this is and how to use
I redid the front page to make it more brief: http://pythonpaste.org/webob/
I stopped with the example, because I couldn't think of a good example.
Maybe a different evening. Suggestions of course welcome.
>> For realistic use cases, some kind of infrastructure is necessary.
> How realistic are we talking? I'm thinking of something that I can
> test by pointing my browser to localhost:8080 or similar. For CGI
> scripts, the standard library's CGIHTTPServer would suffice. How hard
> is it to create something similar for WSGI or for webob?
Well, some kind of WSGI adapter; the wsgiref one is fine. The file
example I guess is boring, because without some kind of dispatch you can
only serve up one file. A most boring server.
Wiki is a common example, but a little too common at this point. WebOb
doesn't offer anything for HTML either, so it would be a somewhat
unsatisfying example anyway I suspect.
Ian Bicking : ianb at colorstudy.com : http://blog.ianbicking.org
More information about the Web-SIG