← Back to team overview

openerp-expert-framework team mailing list archive

Re: User's documentation

 

I support using rST. Documentation is boring enough, the easier to write, the better :)

Albert Cervera i Areny escreveu:
A Dimarts, 15 de desembre de 2009, Albert Cervera i Areny va escriure:
A Dimecres, 9 de desembre de 2009, Albert Cervera i Areny va escriure:
Here's a proposal I made some time ago. Given that now there's a
framework expert's group, here's my second try:
After some discussions there seemed to be an agreement (at least nobody
objected) that at least a new documentation framework would be nice. I have
implemented a first (early) draft and wanted to share what I have to
 receive your feedback. With draft, I mean, that inheritance doesn't work,
 for example.

I haven't had time to work on this by now, but I've been thinking a bit about it and I wanted to share my thoughts.

One of the things that worries me about the module is that it's not very handy when one is developing a new module or writing a long text. rST seems to me a good tool for this.

I think I'd be a must to have conversion tools between rST and the 'documentation' module I sketched.

I envision, for example developers adding a "doc/" directory in the module. There they'd put .rst files which would be automatically uploaded to OpenERP just like it happens with views, for example. One of the things we'd need, though is the possibility of inheritance, and modifying other modules texts. Maybe we should force the creation of a manual ID (again, just like in views). For example:

<cut>

[invoicing_process_title]
Invoicing Process
==============

[invoicing_process_p1]
The invoicing process works this way and not in another one and one must take into account the following things:

[invoicing_process_items]
- This is item number one
- This is item number two

</cut>

Upload process should ensure that each paragraph has an ID and it's unique. We should force adding those IDs, otherwise, people inheriting the module wouldn't be able to properly hook documentation wherever they need.

The previous fragment would create three records in table ir_documentation_paragraph. (The process should be able to upload images too, if they exist in the text.) The first one looking something like this:

{
	'identifier': 'invoicing_process_title',
	'text': 'Invoicing Process',
	'type': 'subsection',
}

Of course, writting new .rST files out of the records in the database should also be possible, and pretty easy to implement.

Now, let's say we create a new module depending on the previous one (which was called 'account') and we need to append another item to the list. It could look something like this:

<cut>

[invoicing_process_item_new:account.invoicing_process_items:append]
- This is item number three

</cut>

We could work with inherited elements similarly to what it's possible with views:

replace -> Replaces the whole paragraph.
after -> Adds the new element as a new paragraph after the inherited one
before -> Adds the new element as a new paragraph before the inherited one
append -> Adds the new element just after the inherited one. That is, without creating a new paragraph.

All this ID stuff would also be used for translations, although those would be handled in .po files.

Comments?





Follow ups

References