openerp-community team mailing list archive

[Pedro Manuel Baeza Romero <pedro.baeza@xxxxxxxxx>]

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 <jeff@xxxxxxxxx>:

> 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 |  jeff@xxxxxxxxx | 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";<rvalyi@xxxxxxxxx>;
> *Date: * Wed, Mar 5, 2014 02:50 AM
> *To: * "Pedro Manuel Baeza Romero"<pedro.baeza@xxxxxxxxx>;
> *Cc: * "openerp-community@lists.launchpa"<
> openerp-community@xxxxxxxxxxxxxxxxxxx>;
> *Subject: * Re: [Openerp-community] About description and manual files
> forOCAmodules
>
> On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero <
> pedro.baeza@xxxxxxxxx> 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
>
>
>