openerp-expert-framework team mailing list archive

[Albert Cervera i Areny <albert@xxxxxxxxxxx>]

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?

-- 
Albert Cervera i Areny
http://www.NaN-tic.com
Mòbil: +34 669 40 40 18