Hi, Jeff, I understand that non technical persons hate to write in a strange semi-programming language, but this is not the case with RST: syntax is pretty straight-forward. You can even split the process in two: functional experts write user manual in plain text and capture snapshots, and a developer, taking very little time, apply RST format.
We need to balance easy of making with possibilities of integration and automation, and I think Raphäel proposal makes this. Regards. 2014-03-04 20:16 GMT+01:00 jeff.wang <j...@osbzr.com>: > Hi gurus, > > Please do think about who will be the author and entertainer of these > .rst files, maybe developer only. think about how many work will need to be > done by developer before commit module to community project, additional > CRAZY hurry OpenERP core version change... > > Too much work for developer, too few chance for a non-technical > person(we call them function expert) involve. > > My suggestion: code for developer, write by developer, review by > developer. use a tool they like. > doc for consultant, write by consultant(init by > developer is ok), review by consultant. use a tool they like. > > As a developer, I hate writing document, and I even hate other > developer don't write document. > > BUT it is life. > > ------------------ > Jeff Wang | j...@osbzr.com | 18016291663 | 02158980787 > @OpenERP_Jeff "As simple as possible, As complex as needed" > <http://www.osbzr.com> > Maintainer of Open ERP china community > http://www.openerp-china.org > > > > ------------------ Original ------------------ > *From: * "Raphael Valyi";<rva...@gmail.com>; > *Date: * Wed, Mar 5, 2014 02:50 AM > *To: * "Pedro Manuel Baeza Romero"<pedro.ba...@gmail.com>; > *Cc: * "openerp-community@lists.launchpa"< > openerp-community@lists.launchpad.net>; > *Subject: * Re: [Openerp-community] About description and manual files > forOCAmodules > > On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero < > pedro.ba...@gmail.com> wrote: > >> Hi, Raphäel, >> >> In this MP, Stefan has embedded an image in the description: >> >> >> http://bazaar.launchpad.net/~therp-nl/account-financial-tools/7.0-add_move_line_no_default_search_period_journal/view/head:/account_move_line_no_default_search/__openerp__.py#L35 >> >> So, there's a way to do it. >> > > Thank your Pedro! I was probably using the wrong path before. > > Then I make the following proposal: > > a module could have README.rst root file. This README..rst file could then > be included into __openerp__.py using an rst include macro such as with the > image example you just pointed. > > Hence if the module is hosted on Github for instance, the module > description is straightforward, right on the project page, just the > projects where the wiki entry page is a README.md file. No fluff so we > don't create too much dependencies on specific module stores. > > example: the request Python HTTP client: > https://github.com/kennethreitz/requests > > Then, we could use the docutils command (or a dedicated wrapper > eventually; docutils supports it well) to automatically convert this > README.md into an HTML *static/description* file (such as > https://www.openerp.com/apps/7.0/openeducat_erp/ ) that would be beginner > and apps friendly, possibly using an OCA HTML template. > > > So this is close to Pedro suggestion, but the idea is this way the > documentation is primarily in all the rst format, that mean it's not lost, > we can work on it, just as if it where code. We also put the content in a > root REAMDE.rst rather than __openerp__.py itself so just browsing the > folder brings the documentation without depending on a python runtime to > extract it from __openerp__.py > > Eventually the documentation is not just one single REAMDE.rst file but a > collection of several files (possibly in a docs folder) and only the > minimal presentation file could be included i the __openerp__.py file. > > so the module I propose would be: > > module > view > model > security > tests > data > i18n > docs #rst to be icluded or linked in the README, Sphinx doc... > static > description #generated > images > __openerp__.py #includes the README rst, or some summary file from docs if > the README is too large > README.rst #primary documentation, possibly including subfiles from the > doc folder > > > Do I miss something? > Thoughts? > > -- > Raphaël Valyi > Founder and consultant > http://twitter.com/rvalyi <http://twitter.com/#!/rvalyi> > +55 21 2516 2954 > www.akretion.com > > >
_______________________________________________ Mailing list: https://launchpad.net/~openerp-community Post to : openerp-community@lists.launchpad.net Unsubscribe : https://launchpad.net/~openerp-community More help : https://help.launchpad.net/ListHelp