#124 Docs need desperate overhaul

open
nobody
General (126)
5
2013-01-18
2005-10-26
Anonymous
No

SQLObject 0.7 as packaged with TurboGears

SUMMARY:
SQLObject docs are out of date:
- many of the examples use import statements that no
longer work
- the examples that use multiple tables are scant
- for an example of db docs that really serve this
niche, see the Django db docs:

DETAILS:
- many of the examples use import statements that no
longer work

#this doesn't work
http://sqlobject.org/SQLBuilder.htmlsub
from SQLBuilder import *

#this works
http://sqlobject.org/SQLObject.html#exported-symbols
from sqlobject.sqlbuilder import LEFTJOINOn

#but this doesn't
from sqlobject.sqlbuilder import RIGHTJOINOn

posting in turbogears:
http://groups.google.com/group/turbogears/browse_frm/thread/91602b3e5a4dfdea/86fa7e464e081edc?q=greenwood&rnum=6#86fa7e464e081edc

- the examples that use multiple tables are scant
How about a simple wiki type example? I'm extending the
TurboGears tutorial (the 20 minute wiki) and I'm
running into all kinds of interesting problems that the
docs don't seem to answer... here are some of my recent
questions:
http://groups.google.com/group/turbogears/browse_frm/thread/41b1dc59e9d15ab3/67d2bd0a35c1e62a?q=greenwood&rnum=7#67d2bd0a35c1e62a
http://groups.google.com/group/turbogears/browse_frm/thread/ef9deab591d6aae/95cd7eb3bea9e5b5?q=greenwood&rnum=8#95cd7eb3bea9e5b5

The idea is, given tables A and B, how do I slice and
dice between the two?

- for an example of db docs that really serve this
niche, see the Django db docs:
http://www.djangoproject.com/documentation/model_api/
http://www.djangoproject.com/documentation/db_api/
http://www.djangoproject.com/documentation/models/

In order for SQLObject/SQLBuilder to be successfull
(and TurboGears, by extension) the docs have to be rock
solid. By that I mean, non contradictory and with
enough examples that a newbie like me isn't left asking
the listgroup basic questions.

-Todd Greenwood

Discussion

  • Ian Bicking
    Ian Bicking
    2005-10-26

    Logged In: YES
    user_id=210337

    The SQLBuilder import has been fixed (r1144)

     
  • Derek Anderson
    Derek Anderson
    2008-02-22

    Logged In: YES
    user_id=1499846
    Originator: NO

    A more comprehensive recipe section would be great too. Learning by example can be more powerful than straight docs. I think that the SQLO docs are actually pretty comprehensive, but they seem to require that you know what you are looking for before you find it, which means you spend a lot of time poring over the docs looking for something that MIGHT be helpful.