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

Hello,

On Mon, 8 Feb 2010 06:31:48 -0800, Adrian Klaver <[email protected]>
wrote:

> +1. Also check out
> http://wiki.postgresql.org/wiki/Python_PostgreSQL_Driver_TODO
> for a more detailed list.

"Add formal documentation page. The PostgreSQL community can do that on
this wiki rather than expecting initd.org to handle it."

Why don't we create a Sphinx-based documentation for psycopg2, as it is
done for many other Python modules?

This will have several advantages:

* unification of the various documents which are in the Git repository
* provide a beginner guide
* serve as static homepage for the not-so-loved http://initd.org
* eventually, provide examples which can be testable as doctests

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/

Any thoughts appreciated.

Regards,

Jonathan