Hi, By experience data have to be declared only once. (I refer to dependency and summary)
If each time you change a dependency/description you have to do it in two places => Risk of Human mistake. So I don't recommend to place the dependency and summary outside the __terp__.py file (or any other future name) Putting documentations usage of module in the module has some drawback: Only people who has access to the bazaar branch of the code could make change. And people that made documentation aren't supposed to code... Maybe a link to the full documentation into __terp__.py should be good. Regards, Nicolas De Smet Albert Cervera i Areny a écrit : > 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. .... > """ > > > 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. > > 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. > > _______________________________________________ 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
