openerp-community team mailing list archive

[Raphael Valyi <rvalyi@xxxxxxxxx>]

Hello, some comments:


On Tue, Mar 4, 2014 at 9:41 AM, Joël Grand-Guillaume <
joel.grandguillaume@xxxxxxxxxxxxxx> wrote:

> Dear community,
>
>
> If I may about this thread, I would prefer to have the documentation in
> the __openerp__.py the way it is done for official one (in .rst).
>
> Having it on an external wiki will be difficult to maintain within the
> module evolution. Having a pdf is no good for the VCS (committing binaries)
> and not easily readable within a review process.
>

At Akretion we are using Gollum ( https://github.com/gollum/gollum ), the
open source wiki initially created by Github and emancipated since then
while still having synergies on the lower level libs like github-markup.

It supports RST out of the box via doc-utils (and also many other markups).
You can even template with OpenERP objects via my erpify and liquid-gollum
gems. That last one also bring OpenERP style wiki page inheritance both for
internal and external pages. Gollum also has many advantages including
extreme hackability, files simply stored in git etc...

I agree that the core doc should primarily live in the VCS i the modules.
But I just want to tell you that eventually Gollum is a great soluton if
you want to build extra end user documentation that will include that RST
documentation like Jeff was mentioning.

Eventually, just like Daniel Reis is making a tool that is automatically
transforming OpenERP modules into modules for pip, we could also have a 20
lines script automated tool extracting automatically a README.rst from the
__openerp__.py, just reformating, adding non RST info in an extra table,
something like that.
Then a simple OpenERP module hosted on Github for instance would have
documentation easily readable by anyone. As I'm hosting a few modules on
Github, I will eventually showcase that usage soon.
But this is just one of the possible use cases.

In any case we should not mix priorities, there is still a lot to be done
at the coding level before thinking about documenting for the masses.

Regards.