README.rst maintainability

[oca]

README.rst maintainability

[sebastienbeau]

👍 for an autogenerated README file, it's a huge pain to update it if something have been added in the template. Generating it from keys based on the manisfest (we can add some extra new keys) seem to be a good solution.

[hbrunn]

generally, pro. But if we lump everything into the description key again, I don't see what we gain, because this one's format also tends to change. I'd then suggest one key per heading in the template, all of them in rst format, and some list keys like contributors and credits following the same/similar semantics as the author key:

{
    'name': 'my name',
    'author': 'Therp BV, Odoo community association (OCA)',
    'contributors': 'Holger Brunn <[email protected]>, Daniel Reis <[email protected]>',
    'intro': 'This module was written bla bla',
    'installation': 'If you need this, this module is not for you',
    'usage': 'Click the shiny buttons',
    'credits': 'OCA <link to what we used>, picol <another link>, fontawesome <and a third link>',
}

This should be quite human readable as it is, and be very simple to press into whatever template we want.

[sbidoul]

The larger problem to address is the one of documentation consistency across distribution media for odoo addons. We must strive to avoid redundancy.

There is now several sources of documentation about an addon:

• the manifest
• the README.rst which contains part of the manifest content
• html content in static/description

Various platforms (inside Odoo, apps.odoo.com, pypi, github, etc) have different requirements for displaying documentation properly (think about images for instance) and it's currently impossible to have one documentation format that avoids redundancy and works nicely on all platforms.

So perhaps the time has come to specify a proper documentation format for Odoo addons.

The defacto standard for documentation in the Python world is Sphinx. It's based on reStructuredText which is itself very powerful and extensible with custom directives.

So I'd go for specifying a Sphinx-compatible documentation structure that would allow generating

• a nice README.rst for github and pypi
• a nice synthetic html documentation for apps.odoo.com
• a complete documentation (if needed) that would be suitable for readthedocs.io and/or a dedicated ghpages site like what is done for connector.

With a couple of custom rst directives and a sphinx-odoo lib, we can probably eliminate all boilerplate content from the documentation.

[pedrobaeza]

The problem would be the same: someone needs to maintain those keys in the manifest. In that scenario, I prefer to keep all together in the README (and with less constraints to not put exactly the needed keys), than split this in other files.

[bealdav]

The object is that there is a bot that check for you:

• are required keys there, to be an accepted PR
• is each block of data is (according keys: usage, configuration) are RST valid ? cc @OSguard to be compatible with http://www.odoo-code-search.com

[pedrobaeza]

We already have checkers on RST format on Travis, so I still don't see this as an advantage. Let's see what others say.

[legalsylvain]

Hi @bealdav, and thanks for your proposal.

About that point, I see Pro and cons :

Pro
Maybe we could have lighter description, with less bug. I mean for example, the lines "test it on runbot", with the id of the repo to recover, the flag of the AGPL / LGPL image, ... Some points are a mess and I guess there are a lot of many errors in the current description.

Cons
We (at OCA) have added a lot of new rules, the last years, and changed a lot the contribution process (flake8 / git / travis / runbot / all the checks for a PR, ...) . Many people say that it's not very easy to contribute. (Hard rule + few review)

I think I prefer to see the Community porting / refactoring and reviewing good code in v10, instead of adding such new changes that will take time. (it's new tool to maintain too, a new bot to do, etc...).

my two cents.

[dreispt]

Confession: the README template is my biggest source of frustration while contribution to the OCA. 😢

[dreispt]

@legalsylvain +1 for a lighter template. Sounds reasonable to just have a standard header and footer, with no placeholders if possible.

[moylop260]

We are auto-creating a section of the main repo description file.
I don't have problem if we have a auto-creation of a section of modules description file.

I mean,

• There are global values shared in all readme files of modules It could be extracted from a root common file by repo.
• There are custom values duplicated from manifest file and readme It could be extracted from manifest to readme.
• There are other custom values that should be filled manually.

Then 👍

[sbidoul]

👍 to autogenerate README.rst

[bealdav]

ping @hbrunn @StefanRijnhart

[EBII]

+1 for an autogenerated README file with big mustach

[mourad-ehm]

👍 for an autogenerated README file.

[lmignon]

👍 to autogenerate README.rst

[StefanRijnhart]

Yes. 👍

[lasley]

Yes this would be awesome & reduce menial maintenance 👍

[dreispt]

It can be quite simple:

• the actual content should go in the description key, and follow the OCA content structure recommendations.
• when this key is set, the README would automatically be generated, adding header and footer text to the description.

[moylop260]

IMHO for description where we could need a multi-line, MD style, images... we could use directly the .md file.

[pedrobaeza]

I think we are going back to the previous steps. Remember: we extracted the description key from the manifest to the README.md. Now we want again to do the contrary.

It's not something useful to step back to insert things in the manifest with other keys to build the README. What about if anyone wants to add other section (see for example https://github.com/OCA/business-requirement/blob/8.0/business_requirement/README.rst)? And it makes sense, because this a generic text. What about if we need another credits section (like the one I added last week for "funders")? We mustn't restrict the format to a close collection of keys in the manifest.

And IMO, they'll be even more obscure to be discovered: you won't know the final README rendering result until the PR is merged and the script launched. There will be for sure more errors than now that you correct contributors in the PR itself seeing the RST preview that GitHub includes.

The only thing that makes sense to automate is the issue link or "Try me on runbot" sections I think, and as that part requires other "magic" to happen (how to deduce the repo-id for example), I prefer to keep it as is.

[lasley]

I'm like @moylop260 idea on the use of the .md itself. Trying to work inside of the keys is a pain, and doesn't come with markdown highlighting in IDEs & I believe this is what we were trying to avoid by offloading into these files.

What would be nice is if we just used the jinja looking vars that are existing in it already, but the question becomes how text is maintained once transposed to the variables.

[bealdav]

@pedrobaeza

What about if anyone wants to add other section (see for example ....

No problem here just use a sub sub title in your description and all is fine in the result

[bealdav]

you won't know the final README rendering result until the PR is merged and the script launched

... say Pedro

I think it's relevant argument there. Instead of use script after PR, we could consider to execute this script locally to produce README from __manifest__.py keys.
Then it joins the best of the two world: manually for users which sleep 4 hours a night and automatic mode for lazy users like me.
What do you think ?

[pedrobaeza]

Well, it's a way to fix that problem, but newcomers will be again in the same hole not knowing that tools that generate the README.

[bealdav]

@pedrobaeza you're right. I see 2 options for newcomers:

• keep README template in maintener-tools repo too or
• use tool like https://pypi.python.org/pypi/bobtemplates.odoo with a customized config with documented helper.

[bealdav]

👍

[moylop260]

we could consider to execute this script locally to produce README

That looks like as cookiecutter

[hbrunn]

why don't we provide a template for odoo.py's scaffold command? I myself use the unholy shell script I created years ago and adapted to the changes through time (technology buy in, for every instance, it was simpler to adapt this than to throw it away and do it right...):

#!/bin/sh

name=$1

if [ -z "$name" ]; then
    echo i need a name
    exit
fi

if [ -d "$name" ]; then
    echo $name exists, doing nothing
    exit
fi

mkdir $name || exit
version="8.0"
repo=$(basename $(pwd))
repo=${repo%%-$version}
repo=${repo%%$version}
cd $name

is_oca=""
if git remote -v 2> /dev/null | grep -q github.com; then
    if ! git remote -v 2> /dev/null | grep -qi therp; then
        is_oca=1
    fi
fi

author="Therp BV"
if [ -n "$is_oca" ]; then
    author="$author,Odoo Community Association (OCA)"
fi

license="# -*- coding: utf-8 -*-
# © $(date +%Y) Therp BV <http://therp.nl>
# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html)."


cat > __openerp__.py <<EOT
$license
{
    "name": "${name}",
    "version": "${version}.1.0.0",
    "author": "${author}",
    "license": "AGPL-3",
    "category": "",
    "summary": "",
    "depends": [
    ],
    "data": [
        'views/templates.xml',
        'security/ir.model.access.csv',
    ],
    "qweb": [
    ],
    "test": [
    ],
    "images": [
    ],
    "pre_init_hook": False,
    "post_init_hook": False,
    "uninstall_hook": False,
    "auto_install": False,
    "installable": True,
    "application": False,
    "external_dependencies": {
        'python': [],
    },
}
EOT

cat > __init__.py <<EOT
$license
from . import models
from . import wizards
from . import controllers
EOT

mkdir models
cat > models/__init__.py <<EOT
$license
EOT

mkdir controllers
cat > controllers/__init__.py <<EOT
$license
EOT

mkdir wizards
cat > wizards/__init__.py <<EOT
$license
EOT

mkdir views
cat > views/templates.xml <<EOT
<?xml version="1.0" encoding="UTF-8"?>
<openerp>
    <data>
        <template id="assets_backend" name="$name assets" inherit_id="web.assets_backend">
            <xpath expr="." position="inside">
                <script type="text/javascript" src="/$name/static/src/js/$name.js"></script>
                <link rel="stylesheet" href="/$name/static/src/css/$name.css"/>
            </xpath>
        </template>
    </data>
</openerp>
EOT

mkdir data images
mkdir -p static/src/js
sed --regexp-extended -e 's/^#.?/\/\//' > static/src/js/$name.js <<EOT
$license

openerp.$name = function(instance)
{
}
EOT

mkdir -p static/src/css
touch static/src/css/$name.css
mkdir -p static/src/xml

mkdir security
cat > security/ir.model.access.csv <<EOT
"id","name","model_id:id","group_id:id","perm_read","perm_write","perm_create","perm_unlink"
EOT

cat > README.rst <<EOF
.. image:: https://img.shields.io/badge/licence-AGPL--3-blue.svg
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3

$(echo $name | awk '{for(i=0;i<length($0);i++){printf "="}}')
$name
$(echo $name | awk '{for(i=0;i<length($0);i++){printf "="}}')

This module was written to extend the functionality of ... to support ...
and allow you to ...
EOF

if [ -n "$is_oca" ]; then
cat >> README.rst <<EOF

Installation
============

To install this module, you need to:

#. do this ...

Configuration
=============

To configure this module, you need to:

#. go to ...

Usage
=====

To use this module, you need to:

#. go to ...
.. image:: https://odoo-community.org/website/image/ir.attachment/5784_f2813bd/datas
    :alt: Try me on Runbot
    :target: https://runbot.odoo-community.org/runbot/{repo_id}/$version

.. repo_id is available in https://github.com/OCA/maintainer-tools/blob/master/tools/repos_with_ids.txt

Known issues / Roadmap
======================

* ...

Bug Tracker
===========

Bugs are tracked on \`GitHub Issues
<https://github.com/OCA/$repo/issues>\`_. In case of trouble, please
check there if your issue has already been reported. If you spotted it first,
help us smashing it by providing a detailed and welcomed feedback.

Credits
=======

Images
------

* Odoo Community Association: \`Icon <https://github.com/OCA/maintainer-tools/blob/master/template/module/static/description/icon.svg>\`_.

Contributors
------------

* $(git var GIT_COMMITTER_IDENT | awk '{$NF=""; $(NF-1)=""; print $0}')

Do not contact contributors directly about help with questions or problems concerning this addon, but use the \`community mailing list <mailto:[email protected]>\`_ or the \`appropriate specialized mailinglist <https://odoo-community.org/groups>\`_ for help, and the bug tracker linked in \`Bug Tracker\`_ above for technical issues.

Maintainer
----------

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

This module is maintained by the OCA.

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

To contribute to this module, please visit https://odoo-community.org.
EOF
fi

mkdir tests
cat > tests/__init__.py <<EOF
$license
from . import test_$name
EOF

cat > tests/test_${name}.py << EOF
$license
from openerp.tests.common import TransactionCase


class Test$(echo $name | sed -e 's/^\([a-z]\)/\u\1/g' -e 's/_\([a-z]\)/\u\1/g')(TransactionCase):
    def test_$name(self):
        pass
EOF

mkdir -p static/description
base64 -d > static/description/icon.png <<EOF
iVBORw0KGgoAAAANSUhEUgAAAFAAAABQCAMAAAC5zwKfAAAABGdBTUEAALGPC/xhBQAAAAFzUkdC
AK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAAVNQTFRF
AAAANM73NtH2Nc73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73Nc73NM73NM73NM73NM73
NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73
NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73
NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73
NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73
NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73NM73AAAAvo3V
DAAAAHB0Uk5TAAAAAAEEAg4XdwprLQUFIKWUP0OonZ6iJ6RclzEzNao5Wn06WysqRrQ3LBU+ER4a
Lqc4CyEIKKGgrd6mo1A8SbFfJUvEex2V1gYWBzafVIYUvC+CDbpdamxmElMwk29uaBOcA1UMHE+H
kU0y0CYYqxD6ZVAAAAABYktHRACIBR1IAAAACXBIWXMAAA3XAAAN1wFCKJt4AAABlUlEQVRYw+3U
6VOCQByA4aUWPJLUMtHssAMztNSKoKT7kizL7tOyu+z4/79VIpdOpgNOzrTPJ3bBd/CnswAgyD8B
cZODGGzs+xImB3GL2QPAGjoABEGaGMTVAwDDTTiurDa7Gm9z6O4RZLsWWdPh63SpZx50d+judXq6
NLyUr6ag/+dgd6CnV9XXHzQaHBjUDSAwZDQ4XG+QpunQSHiUljARzB0dY2h5Oa4EY8XNeGJiMkSr
mCnITjOajRDgOI6fmU1yEmEOuOcXhNKKX+Sh/JWX/N87lGd5ZZXnFMIaub5BqWt/CrAsK/oSm2lW
gkN3tKV0zYpb24QcJEt7ILMjXxYfaYWaFbubrT7DPS+h/1G+ZParDPDg0HjQ7oR1BY/Cxycap2fn
ZcGLS7yeIB7KXWnkrvPlwd4bsp6gWDGmzJ8EkxExLbn9NXhXHvTepxV56W/zkHXxEuoRPAXVh+nn
yuCLTb8uvFK8QkgV98i3uMwK3tWzEbCxyuPPEikLfhQcyscdDDBMN0MzNH8QQRAEQRAEQar4BCa3
ZCwzh7jfAAAAJXRFWHRkYXRlOmNyZWF0ZQAyMDEzLTA5LTE4VDEzOjUwOjMyKzAyOjAwi3zE5QAA
ACV0RVh0ZGF0ZTptb2RpZnkAMjAxMy0wNy0wN1QxMzoyMzo1OSswMjowMGF0NUsAAAAASUVORK5C
YII=
EOF

if [ -n "$is_oca" ]; then
base64 -d > static/description/icon.png <<EOF
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
EOF
fi

[bealdav]

provide a template for odoo.py's scaffold command

👍 thanks

[lmignon]

@hbrunn at ACSONE we use https://pypi.python.org/pypi/bobtemplates.odoo

[bealdav]

Another tool https://github.com/0k/cookiecutter-odoo

bob vs cookie battle ?

Which is the best ?

[dreispt]

There are two different topics discussed here:

First is an automatic generation of the README:
The OCA template is necessary, but too cumbersome (and error prone) to fill in.
It could be generated from the information on the manifest and a description.txt.
I tried a Python proof of concept and it is quite simple to achieve.
Initially this could be a manual command, but we could later consider it to become automated.

The module structure scaffolding is a different topic.
Odoo already has a scaffold command, why not use it?
For bonus points, the OCB distribution could bundle it.
It could be a bare bones version of the maintainer-tools "template".

[elicoidal]

I am coming late into the thread but still have some comments/questions.
Most of the time the current README template is not filled in properly and simplifying it/prebuilding it is a better solution.

• Nevertheless, I agree with Pedro that this is annoying that the README is generated after PR is merged.
• Besides what if the module comes with a README (for whatever reasons)?
• And coming back to question #238 (comment), and the 3 sources of information.
  Are they compatible with each other...? can we add rst in the description key so that it renders properly in Odoo settings?
  (I remember issues for the images rendering between the odoo.com, the Odoo settings and rst format)
  What about the static content (html)? It surely can be generated from rst/sphinx.

[dreispt]

OK, we could keep using the README.rst, just like we do today, and add an automated step that automatically fills in placeholders, like the version, branch, repo id, etc.
That alone would be a great step forward and would solve this issue.
Also it does not involve significant workflow changes and is easy to implement.

But it still misses "the larger problem to address is the one of documentation consistency across distribution media for odoo addons" (@sbidoul's #238 (comment)).

Quoting @sbidoul's proposal:

So I'd go for specifying a Sphinx-compatible documentation structure that would allow generating

• a nice README.rst for github and pypi
• a nice synthetic html documentation for apps.odoo.com
• a complete documentation (if needed) that would be suitable for readthedocs.io and/or a dedicated ghpages site like what is done for connector.

With a couple of custom rst directives and a sphinx-odoo lib, we can probably eliminate all boilerplate content from the documentation.

While this goes beyond this issue's scope, it is a relevant discussion.
A first approach could be to keep using the README.rst as the main source (as proposed above) and just automatically generate the HTML description files from it, to correct presentation at apps.odoo.com.

[bealdav]

I don't understand why we can't keep the manual way (Readme tmpl) for newcomers and the automatic way (auto processing) for maintainer-tools addict (in local way) ?

[dreispt]

@bealdav my short term proposal achieves that: README is manual and any placeholder left behind can be automatically filled by a tool. Later that tool can be used by a bot doing the missed replacements.

[dreispt]

Recovering this discussion:

I propose that we move all OCA boilerplate to the footer of the README.
This makes it much easier to updated the README boilerplate to more recent versions, both manually or scripted. I can prepare a PR for that.

[bealdav]

👍 to put all at the end of the README.
For updating, the easiest way is to define a link to an image. This image could include all boilerplate, then for update, just change the image and all modules of the repo/branch updated at once.
May be an image by repo.

[yvaucher]

@dreispt not sure what you include in the boilerplate. We could have a section on top limited by some comment as start and end tags. Or define a limited part which can be change. Anyway some comments must be added to let the editor know what he can edit or not. Of course the part which change the most should be on top as it is what you are looking for when you open the file or look at the description inside apps.odoo.com.

[sbidoul]

Done in #339