Hi Albert, On 12/09/2009 11:55 PM, Albert Cervera i Areny wrote: > Here's a proposal I made some time ago. Given that now there's a framework > expert's group, here's my second try: > > I think docs should be integrated with modules. I wanted to make a proposal > for a documentation system for OpenObject. Let me explain it here. > > I'd use DocBook with XML for documentation. Simply because it's easily > parseable. I think each paragraf and title should have an id which could then > be referred by modules that depend on the current module, just like views > work. For example: > > Module T: > > <title id="summary">Summary</title> > <para id="intro"> > This is a summary of the module one that does this. > </para> > > Module TT (which depends on T): > > <para id="intro" position="replace"> > This is a summary of the module one that does this and that. > </para> > > Of course, there would be "replace", "before", and "after" options as always. > Also you could add special tags in the code (which docbook automatically > ignores), like a field reference: > > <para id="explanation"> > The invoicing process won't work unless partner's <field > ref="res.partner.vat">vat</field> field has a correct value. > </para> > > This "extra" information, would be parsed when the module is installed and > appended to field documentation so when the user sees a question marc in a > field sees current documentation plus theh places where the field is referred > to in other parts of the documentation. > > For example, in the "res.partner.vat" case one would see: > > """ > Description: Value Added Tax number. Check the box if the partner is > subjected > to the VAT. Used by the VAT legal statement > > References: > > * .... The invoicing process won't work unless partner's vat field has a > correct value. .... > """
I don't think it'd be a good idea to place extra info for fields into the docs. Fields have to be documented in the code. > > > Well, I think you get the idea of the whole thing. I believe something like > this would make OpenERP have an incredible documentation system I doubt > others have. > > If people contribute or not to the docs is a matter of forcing people to do > so. For example, in PostgreSQL absolutely no patch gets commited if it > doesn't change docs acordingly. Without commitment no doc system will be > useful. True > > By the way, I'm willing to implement this system if the we agree this will be > OpenObject's way of document things. But we need to agree on that first. +1 -- Simone Orsi simone.orsi<at>domsense.com Via Alliaudi, 19 - 10064 - Pinerolo (TO) - Italy Mobile: (+39) 3475004046 - Fax: (+39) 01214469718 Domsense Srl http://www.domsense.com _______________________________________________ Mailing list: https://launchpad.net/~openerp-expert-framework Post to : [email protected] Unsubscribe : https://launchpad.net/~openerp-expert-framework More help : https://help.launchpad.net/ListHelp
