openerp-expert-framework team mailing list archive

[Albert Cervera i Areny <albert@xxxxxxxxxxx>]

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. 

Note that it will require latest Koo revision (from bazaar) because I added 
the possibility of rendering web content from a field value (instead of 
considering field's value as the URL). Of course, using Koo wouldn't be a 
requirement for the final framework but using it was simply easier for me.

Attached you can find the module (documentation.zip) and several screenshots 
which I explain below:

As you can see I thought of using a tree like structure, take a look at 
index.png, for example.

In image form2.png you can see the basic paragraph form, containing the 
information of the main documetation title. In image form3.png you can see how 
the current paragraph is rendered (on the left) and the rendering of the same 
element plus the rest of its children (on the right).

As you can see, images can also be included in documentation, you can see how 
in form4.png. If the paragraph contains the special tags "<field/>" or 
"<view/>" like in form1.png, it will be automatically parsed and references to 
fields and views added as seen in form5.png.

So far, I see advantages and disadvantages with the current aproach. Although 
it's true that it's possible to use OpenERP to create the documentation, it's 
also true that it's a bit slow to create each record, specially for "title", 
"section", etc. (which don't have a lot of text). Though, that might be easily 
solved making the list editable.

The other problem I see is that if inheritance is done at "paragraph level", 
it'd be hard to add a new entry when there's a list of options. Documentation 
writers would be forced to repeat all options. Not sure if that would be very 
frequent or a grave problem, though.

I think we won't need title, section, subsection as I've implemented. Probably 
it'd be enough to keep only "title", and text size should change depending on 
it's depth in the index.

Once implemented, it'd should be pretty easy to create new backends, so we 
could extract documentation to latex, docbook or directly to any reporting 
engine to create PDF documents.

It also occurred to me that'd be also interesting to let users add their own 
comments, so they could add annotations they would see each time they "ask for 
help".

Comments? Suggestions?

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

Attachment: form2.png
Description: PNG image

Attachment: form3.png
Description: PNG image

Attachment: form1.png
Description: PNG image

Attachment: index.png
Description: PNG image

Attachment: menu.png
Description: PNG image

Attachment: documentation.zip
Description: Zip archive

Attachment: form4.png
Description: PNG image

Attachment: form5.png
Description: PNG image