← Back to team overview

openerp-expert-framework team mailing list archive

Re: User's documentation


Hello guys,

I don't know if you got that, but my Ruby OOOR connector for OpenERP is able
to draw UML diagrams of any OpenERP classes since version 1.2.3. It uses the
ir_model and ir_model_fields table to draw the UML, meaning even
fields.function are properly displayed unlike tools that just connect to the
database schema.

Yes, there are the end users, but before dreaming about end users able to
use OpenERP out of the box, I think it's good to make sure non alien tech
people at least can grasp it. Then may be it will eventually mature enough
into something accessible for the tech disabled guys too. So I think we
could eventually attach such an UML drawing inside some modules. At least,
for integrators, it's useful to know the command to quickly reverse engineer
some module you don't know yet. Taktik.be started using it too and have
fallen in love with it.

It's specially space savy when drawing the relations, reusing the same
borders for reverse relations (like one2many / many 2one or two sides
many2many). However, you can't generally draw the whole UML: it's too large:
you can't read it and it will even make an out of memory in dot. However,
it's very useful to document a set of classes with their directly connex

I implemented it in OOOR because for me in Ruby it was a snap (I hadn't more
time to waste), now if some Python red neck wants to rip the code and makes
it an OpenERP module that document any OpenERP Object or collection of
objects, then be my guest. Calling Ooor via a Python method inside an
OpenERP module (ruby command line, just like when you call dot) would also
be pretty easy and cross platform.
The specific part of OOOR that draws UML is here:
It looks like it's larger than it should be. Actually it's because to save
space, we collect all the relations first and then only draw them in a
factored way.

You can find such an example here:
and the UML tutorial here:
Whole OOOR tutorial / API here:

In the future, I would like to implement serializing the schema in YAML.
Then I could easily spot any schema change between two schemas. Meaning we
could have a cool feature showing all the relational exertions brought by
some module. So for instance in the UML diagram you would see in green all
the new objects and newly added relations. That would be very handy to
document modules then. I guess I need a half day to implement that properly
(in OOOR).
I hope I could do that over the next month. That could be especially cool if
we had a function in module that would install the module, draw the UML and
roll back the module installation. So you could know how a module looks like
before installing.

Next, I would like to be able to automatically spy the OpenERP trunk branch
with a Robot (actually inside a Google Wave) and highlight all schema
changes done since 5.0 release locally at each commit and also globally. I
remember we talked about that with Fabien. I proposed him their devs would
use a special commit flag like [SCHEMA_CHANGE] to highlight the data
structure changes and make our migration life easier. He said he didn't want
to change their process and would like this to be automated. Well they
didn't do anything yet. But at least I'm close to that automated bot. I
think in like one day and a half I could program such a Google Wave robot
everyone could look at/subscribe and log additional comments such as
community maintained migration scripts. Hope I find time soon.

Let me know if you find OOOR UML useful.

Raphaël Valyi

On Wed, Dec 30, 2009 at 2:48 PM, Cloves Almeida <cjalmeida@xxxxxxxxx> wrote:

> I support using rST. Documentation is boring enough, the easier to write,
> the better :)
> Albert Cervera i Areny escreveu:
>> A Dimarts, 15 de desembre de 2009, Albert Cervera i Areny va escriure:
>>> A Dimecres, 9 de desembre de 2009, Albert Cervera i Areny va escriure:
>>>> Here's a proposal I made some time ago. Given that now there's a
>>>> framework expert's group, here's my second try:
>>> After some discussions there seemed to be an agreement (at least nobody
>>> objected) that at least a new documentation framework would be nice. I
>>> have
>>> implemented a first (early) draft and wanted to share what I have to
>>>  receive your feedback. With draft, I mean, that inheritance doesn't
>>> work,
>>>  for example.
>> I haven't had time to work on this by now, but I've been thinking a bit
>> about it and I wanted to share my thoughts.
>> One of the things that worries me about the module is that it's not very
>> handy when one is developing a new module or writing a long text. rST seems
>> to me a good tool for this.
>> I think I'd be a must to have conversion tools between rST and the
>> 'documentation' module I sketched.
>> I envision, for example developers adding a "doc/" directory in the
>> module. There they'd put .rst files which would be automatically uploaded to
>> OpenERP just like it happens with views, for example. One of the things we'd
>> need, though is the possibility of inheritance, and modifying other modules
>> texts. Maybe we should force the creation of a manual ID (again, just like
>> in views). For example:
>> <cut>
>> [invoicing_process_title]
>> Invoicing Process
>> ==============
>> [invoicing_process_p1]
>> The invoicing process works this way and not in another one and one must
>> take into account the following things:
>> [invoicing_process_items]
>> - This is item number one
>> - This is item number two
>> </cut>
>> Upload process should ensure that each paragraph has an ID and it's
>> unique. We should force adding those IDs, otherwise, people inheriting the
>> module wouldn't be able to properly hook documentation wherever they need.
>> The previous fragment would create three records in table
>> ir_documentation_paragraph. (The process should be able to upload images
>> too, if they exist in the text.) The first one looking something like this:
>> {
>>        'identifier': 'invoicing_process_title',
>>        'text': 'Invoicing Process',
>>        'type': 'subsection',
>> }
>> Of course, writting new .rST files out of the records in the database
>> should also be possible, and pretty easy to implement.
>> Now, let's say we create a new module depending on the previous one (which
>> was called 'account') and we need to append another item to the list. It
>> could look something like this:
>> <cut>
>> [invoicing_process_item_new:account.invoicing_process_items:append]
>> - This is item number three
>> </cut>
>> We could work with inherited elements similarly to what it's possible with
>> views:
>> replace -> Replaces the whole paragraph.
>> after -> Adds the new element as a new paragraph after the inherited one
>> before -> Adds the new element as a new paragraph before the inherited one
>> append -> Adds the new element just after the inherited one. That is,
>> without creating a new paragraph.
>> All this ID stuff would also be used for translations, although those
>> would be handled in .po files.
>> Comments?
> _______________________________________________
> Mailing list: https://launchpad.net/~openerp-expert-framework
> Post to     : openerp-expert-framework@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openerp-expert-framework
> More help   : https://help.launchpad.net/ListHelp