openerp-community team mailing list archive

["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"
                    
      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
 +55 21 2516 2954
www.akretion.com