openerp-community team mailing list archive

[Yannick Vaucher <yannick.vaucher@xxxxxxxxxxxxxx>]

Including a README.rst seems a good idea to be compatible with github.
Did you succeed in such inclusion? I tried a bit but couldn't do it as for
images.

Otherwise +1 for keeping rst format for dev (README.rst or __openerp__.py)
and for html for end users with a OCA template would be great.

Cheers,


On Tue, Mar 4, 2014 at 7:50 PM, Raphael Valyi <rvalyi@xxxxxxxxx> wrote:

> 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
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openerp-community
> Post to     : openerp-community@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openerp-community
> More help   : https://help.launchpad.net/ListHelp
>
>


-- 
Yannick Vaucher
Business Solutions Software Developer

Camptocamp SA
PSE A, CH-1015 Lausanne
Phone: +41 21 619 10 30
Office: +41 21 619 10 10
http://www.camptocamp.com/