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 | [email protected] | 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";<[email protected]>;
Date: Wed, Mar 5, 2014 02:50 AM
To: "Pedro Manuel Baeza Romero"<[email protected]>;
Cc: "[email protected]"<[email protected]>;
Subject: Re: [Openerp-community] About description and manual files
forOCAmodules
On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero
<[email protected]> 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_______________________________________________
Mailing list: https://launchpad.net/~openerp-community
Post to : [email protected]
Unsubscribe : https://launchpad.net/~openerp-community
More help : https://help.launchpad.net/ListHelp
