openerp-community team mailing list archive

[Raphael Valyi <rvalyi@xxxxxxxxx>]

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