Re: Psycopg documentation (was Re: State of PostgreSQL's drivers in Python)

On Tue, 9 Feb 2010 05:39:21 +0000, Daniele Varrazzo
<[email protected]> wrote:

> I have been involved in Epydoc in the past and I have arrived to the
> conclusion that automatic api generation is not that useful, so I
> wrote psycopg documentation "by hand". I decided to not just gather
> the files available in the doc directory (I am the author of the
> "extensions" file it was there) but re-organized everything from
> scratch. There is an "usage" section, advanced topics, description of
> the objects and the modules.
>
> The repository is available on http://github.com/dvarrazzo/psycopg2 .
> The documentation can be previewed on
> http://piro.develer.com/psycopg2-doc/

Hey, this is great!
That's what I wanted to do after the cleanup from the old doc directory,
but I didn't even had the chance to do it ;)

I quickly read it and found some typos which have been commited into a
fork on Github.

>> Please keep on doing this. It is sorely needed. There once
>> was a FAQ on initd.org which contained various morsels of
>> wisdom, too.
>
> I think the documentation I've put together is a good starting point
> (well, it's almost finished: 80% i'd say). There are a bunch of
> "todo": a few things are just to be finished, for other I need
> clarification from the author or the ML. It would be nice to receive
> feedback about anything to be added or fixed.

It's pretty good, I like it :) The only comments I have so far are:

* we should make a clear distinction between *psycopg* and *psycopg2* in
the documentation itself (I think the Python's code speaks by itself)

* I find the paragraph on query parameters is a bit alarming. Maybe
something simpler like "To avoid SQL injections problems, do this:
...", with maybe some "don't do this, don't do this, but do this"?

* I wonder if we should make a clearer distinction between the DB-API
interface and the extensions on standard objects (I'm thinking about
.fetchXXX() methods and iterating over a cursor object for ex.).
This would have the benefit to document precisely what psycopg offers
that the DB-API doesn't, but I'm not sure this is a good idea, though
(I mostly speak aloud here).

If you need some help to fill some empty pages or fix some todo, just
ask.


Regards,

Jonathan