A Dijous, 10 de desembre de 2009, Zyphos va escriure: > 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.
That's not necessarily true. Currently translations are packaged with each module but updated at launchpad. However, I think currently there are more chances developers document something (sure that's quite optimistic already), than users doing it. > And people that made documentation aren't supposed to code... > > Maybe a link to the full documentation into __terp__.py should be good. Having docs outside has the problem of updates on new versions and no synchronization between source repository and doc. > > 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. > -- Albert Cervera i Areny http://www.NaN-tic.com Mòbil: +34 669 40 40 18 _______________________________________________ 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
