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.
