openerp-expert-framework team mailing list archive

[Zyphos <zyphos@xxxxxxxxx>]

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.
>
>