Guido van Rossum wrote: > 2007/10/22, Ian Bicking <[EMAIL PROTECTED]>: >>> 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: >> >> http://pythonpaste.org/webob/class-webob.Request.html >> http://pythonpaste.org/webob/class-webob.Response.html > > 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 > it. 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 : [EMAIL PROTECTED] : http://blog.ianbicking.org _______________________________________________ Web-SIG mailing list Web-SIG@python.org Web SIG: http://www.python.org/sigs/web-sig Unsubscribe: http://mail.python.org/mailman/options/web-sig/archive%40mail-archive.com
