Pragmatic model documentation with RUM

[Michael Brickenstein]

Hi!
Do you know that for each model,
rum defines a page:
/<model>/_meta
as here:
http://demo.python-rum.org/directors/_meta (sorry the demo is not up to date to demonstrate the new features)

This page displays the fields in the RUM application
for your model.
Most of those fields are automatically generated by RUM for your
models, but can be customized.
In particular, those fields contain much essential information about your model
properties: name of columns/fields/attributes, type, maximal lengths, default values, ...
Moreover, RUM fields have a class. Whenever you register a special field class like Url, HTML instead of String/Text/Unicode,
it's also available in the _meta page.

RUM fields can correspond to
- columns from your database
- properties from SQLAlchemy: relations, column properties
- other arbitrary properties of your objects (you have to register such fields explicitly)

I suppose that Alberto constructed it initially for debugging a RUM applications behaviour.
I added a few features which make it a little bit more like a documentation about your model:

- most importantly: each field class has now an 'description' attribute. This description can contain additional documentation.

For Postgresql, I support column comments. Each column can be commented inside a database.

http://www.postgresql.org/docs/8.3/static/sql-comment.html

This is a standard way (in Postgresql) to document database. Comments entered this way are not just in your web application,
but available for everybody. Try try \d+ in psql

Since, there are other databases than Postgresql and not every property corresponds to a column in your database,
it's of course also possible to document fields in Python.

for example:

from rum.fields import description_for
from collections import namedtuple

D=namedtuple('D', 'resource field_name description')

description_for(
model.Person,
'favorite_cookies',
'Cookie names should follow american conventions.'
)

- for Relation fields the related class _meta description is linked
- for Foreign Keys the contraints target column is displayed.
- for Relation fields RumAlchemy tried to reflect the actual SQL expression

Cheers,
Michael

[Michael Brickenstein]

I just added as new feature
generated documentation (pydoc) of the resource class.

Cheers,
Michael

> --
> You received this message because you are subscribed to the Google Groups "rum-discuss" group.
> To post to this group, send email to rum-d...@googlegroups.com.
> To unsubscribe from this group, send email to rum-discuss...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/rum-discuss?hl=en.

-------------------------------------------
Dr. rer. nat. Michael Brickenstein
Mathematisches Forschungsinstitut Oberwolfach gGmbH
Schwarzwaldstr. 9 - 11
77709 Oberwolfach
Tel.: 07834/979-31
Fax: 07834/979-38