Is there a way I can create database documentation from model documentation

Question

I'm finishing a certain django project. It's a data entry application with more than 170 tables in a postgresql database. The application would primarily serve to support a large data entry operation that would last about 2 months. After that it would only serve to export the entered data as xml and json. Plus people may use just the database as is to build reports on.

What I need is a simple way to build online documentation for the database tables and columns and the XML entities and attributes which are all named after the models and model fields (attributes) (XML exports are built with the standard django model serializer). I'd like to have this documentation in 2 languages (or one but it wouldn't be english, so it would need UTF8). It would also be very nice if I could store the database documentation directly into the postgres db as table and column comments. Note that model inheritance is used for a big part of all the models.

Does anyone have a general idea how I should approach something like this?

EDIT:

I forgot to mention that I've to assume that people reading all this docs would be completely unfamiliar with Django and how stuff is structured in a django project. So basically I need a way to tell people "This table stores data for that and this field stores values for that".

Answer 1

You might want to take a look at Sphinx. The tool is used quite widely (inc. Python docs). It allows you to create your documentation in a semi-automatic way. I find particularly the autodoc extension handy.

You may need to develop a custom extension for Sphinx should you wish to hook it up with your XML files. This ought to be relatively straightforward, though.

Answer 2

You can attach the documentation to the actual database meta-data using COMMENT. Then you can iterate over that data using the information_schema, and pg_catalog. You can see how to get to those comments very easily by using psql's -E argument in conjunction with \d_+ - where the underscore is a character specified in \? . This permits the docs to be close to the database and retrievable outside of it, rather than two discrete things.

COMMENT ON TABLE schema.table IS $$ FOO BAR BAZ $$;

psql -E -d database;
database=# \dt+ schema.table;

The \dt+ is the command specified by \?, the t is for table;

database=# \?

Informational
  (options: S = show system objects, + = additional detail)
  ...
  \dt[S+] [PATTERN]      list tables

Answer 3

If you also want to create a good looking ER diagram, there is a great project which introduces the ./manage.py graphmodels command: http://code.google.com/p/django-command-extensions/ It also includes many other very useful commands.

For creating a graph of your models you need GraphViz, the installation may be a bit complicated, but the results are amazing. An example: http://ido.nl.eu.org/static/images/pycon_no_grouping.png