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

On Mon, Feb 8, 2010 at 6:00 PM, Karsten Hilbert <[email protected]> wrote:
>> As a user of psycopg2, I was often bite by the lack of easily readable
>> documentation. Even if the module follows the DB API, it adds several
>> functionalities which are hidden within the examples (AFAIR, I thinking
>> about listen/notify support, copy, async functions, connections and
>> cursors
>> factories, etc.)
>>
>> This morning after reading the thread on pgsql-hackers, I started to work
>> on this.
>> Currently, this is a big work-in-progress: I started to move documents
>> from
>> / and /doc into one place, cleaning them up a bit as I moved them. I might
>> borrow some of the links Marko set up on the Psycopg wiki page on
>> PostgreSQL's wiki.
>> For now, the code is in a branch at
>> http://github.com/multani/psycopg2-sphinx-doc and the generated doc is
>> (temporarily) at http://multani.info/projects/psycopg2/

Sorry, I've been out of this mailing list for a long time.

Amazingly, yesterday morning I decided too to start (...and finish)
the psycopg documentation. I made the promise to Fog at the Italian
Pycon3 and I want to finish at least for Pycon4. Plus, I wanted to
tale a look at Sphinx.

I pushed my files on github, went to the search bar to look at my page
as anonymous user... and found your project pushed just a few hours
before. :-\

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/

> 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.

Thank you very much. Sorry Karsten: if I had read the ML yesterday
morning I would have saved you some time.

-- Daniele