villas, you're right! I had forgotten the conclusion of our previous discussion ... I'll try not to be so "lazy" next time, but truth be told, my plate spilleth over. Anyway, the epydocs need lots of work and the formatting leaves something to be desired. But I believe the self-documenting nature of it makes it a winner.
On Mar 26, 5:39 pm, villas <[email protected]> wrote: > I think we all agreed that a concise reference is important. However, I > thought previous discussions had led to the conclusion that we should > concentrate on writing better docstrings. See existing > epydoc:http://www.web2py.com/examples/static/epydoc/index.html > > > > > > > > On Monday, 26 March 2012 01:22:14 UTC+1, weheh wrote: > > > I think I made this point a couple of years ago. I'm too lazy to go > > and try to dig up the thread. Here's my 10 cents. > > > I agree strongly that the current manual tries to be both introductory > > tutorial and reference. I also agree it's been hugely improved since > > v1 and is extremely useful. The cookbook should also prove to be a > > valuable resource. > > > However, as a rare divergence in opinion from Massimo's, I strongly > > DISAGREE that we need a second, more introductory manual. Instead, I > > think we need a very concise, very dense reference manual. Here's my > > rationale. > > > Although the v2 and v3 manuals have been made searchable online, the > > information about certain commands is still spread out all over the > > place. The way the manual works, it takes a long time to download, the > > TOC of each chapter to render, and then for the search to paginate you > > to the appropriate place in the doc. That's cumbersome, but it works > > IF you know what to search for. There is no index. And even if you do > > have the right search term, you often end up having to look in > > multiple chapters. In some cases, there's a lot of verbiage to consume > > as well. > > > I suggest we, as a community, invest time in a unix-like man page or > > python-like doc reference. Each command of web2py to be listed, one to > > a "page". Each command should have its complete signature described in > > gory detail. In cases like Auth, there needs to be a complete listing > > and description of its many class variables. There absolutely has to > > be a cross-linked index, which should be the primary point of entry > > into the document. The reference should be searchable as well. Each > > web2py command/helper/whatever needs to have a short example. One > > thing I don't like about python doc is that it's extremely slim on > > examples vs. unix manuals, which have always had some short example or > > two. > > > I think web2py has enough tutorial material for the time being. I'm > > not saying it can't be improved. But if we split out a reference, it > > will make tutorials easier to create in the future. Tutorials could > > then be more task-directed, like the cookbook. And whenever a new > > command or thingie gets added to web2py it can be easily added to the > > reference.
