Ian Bicking <ianb@...> writes:
> I can tag the documentation at the time of release. However, the issue
> is that current documentation is often more accurate with respect to
> older versions than is the documentation in those older versions. But I
> just can't bring myself to go through the effort to backport
> documentation fixes.
I am still in debt with you with regards to finding something to put docs in
the code and using it for testing, as we've discussed a while ago. I'm sorry,
but I've been too busy (and to make things "worse", I've subscribed to try
getting my M.Sc. in electrical engineering ;-)) and couldn't put my hands on
But, back to the point, I think that having newer docs more accurate is a
natural consequence as is also the case with code. Small bugfixes make the
intentions you (the SQLObject team and authors) had when you wrote the code.
Small bugfixes to documentation make it clearer and more accurate with what
the author tried saying.
If this separation occurs, won't docs be left as secondary and lag behind the
code too much? I'm a lot concerned with this lagging because there are
already a lot of things that aren't clear in the docs and I think need being
How to do that? My idea is writing a tutorial for starting -- I've started
something for my own use and I don't feel it is in a publishing state not even
as an 'alpha' release ;-) -- where people can see a few more complex use
Obviously the tutorial won't be enough to replace documentation, but it would
be a nice complement to it and would link to the key points at the docs,
filling some of the gaps I think are missing or need being make more clean
and (why not?) more obvious...
How I thought it:
- start with actual docs (specially the Person class)
- evolve them to make a sequence to create something like an address
book, employees catalog, etc., including BLOB objects (employee
photos, pictures from friends, something like that)
- show how to create everything using SQLObject
- show how to create an app using 'fromDatabase = True'
- present basic operations in an ordered way:
- introduce transactions while working with two tables at the same
- present how ForeignKey works and how it can be used to make the
process of getting and updating data easier
- present more "advanced" concepts:
- getting the connection object to
- execute arbitrary queries
- (see if there's something interesting and that works
with PostgreSQL + SQLite here)
- use the connection hub in different files (more than one
'.py' with code)
- write some application that creates a session per user,
allowing the use of database restrictions and policies to
GRANT or not access to data
This is an introductory and very simple tutorial, where people will be able to
see more of SQLObject and see it in a "real world" application (at least it
has a bit more of classes, and should be running at the end of the tutorial).
At first I was thinking on making it simple, with no user interface at all, so
that the developer that is following the tutorial can "glue" it to his/her
favorite UI toolkit.
And, since TurboGears is also a very interesting tool, and using it with
SQLObject to write wep apps is very pleasant, I thought about using the first
tutorial as a base for a second one, where a web interface written with
TurboGears would be added to it. But this is another thing for my wishlist
Sorry for missing the topic of your post... :-(
Jorge Godoy <godoy@...>