Am Samstag 12 Dezember 2009 13:09:17 schrieb Simone Orsi: > 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 > please do not forget to implement a possibility to add site and/or company specific documentation. -- Best Regards
ChriCar Beteiligungs- und Beratungs- GmbH http://www.chricar.at/ChriCar/index.html Dr. Ferdinand Gassauer Official Tiny Partner _______________________________________________ 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
