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?