[RFC] README.rst generator

[sbidoul]

This follows #295 and a discussion with @elicoidal while working on the mis builder documentation.

Currently the README.rst is created manually by module authors. It contains

• a mix of hand-written information (description, usage, credits, etc),
• boiler plate OCA text (eg reference to OCA maintainers, link to runbot, link to issue tracker),
• some information that is redundant with the manifest (eg license badge)

The current situation makes it difficult to maintain consistency across OCA addons in the boilerplate text. It also makes it difficult to ensure consistency between the manifest and the README (eg for the license badge and the upcoming development status).

This is a proposal to let authors write the relevant text in small files and have the README.rst be generated nightly.

Proposal

Let authors create reStructuredText fragments in the addon root directory,:

• introduction.rst
• installation.rst (optional)
• configuration.rst (optional)
• usage.rst
• developer.rst (optional, developer instructions)
• roadmap.rst (optional, known issues, future ideas)
• contributors.rst (optional)
• credits.rst (optional, additional credits other than authors and contributors)
• history.rst (optional, the changelog)

Each rst fragment should be composed of body text (paragraph, lists, tables, images) and must not contain any section title.

Create a new script oca-gen-addon-readme that generates README.rst for each addon in a repo where introduction.rst and usage.rst are present. The sections content is drawn from the rst files. Section titles are not generated if the corresponding rst file is absent. Title, license badge and development status badge are obtained from the addon manifest. If introduction.rst or usage.rst is missing, README.rst is left unchanged.

Update the nightly job that updates repos README.md to invoke oca-gen-addon-readme too.

[sbidoul]

I just updated the text above to move the fragments to the addon root directory. This is to avoid issues when the docs directory is used to contain a sphinx documentation like @guewen does in connector.

[elicoidal]

Another point, probably implicit: the README should not be regenerated if no change happened in the doc directory either.
I would add a section developer (optional) in your list but not essential indeed.
Shall we think about introducing CONTRIBUTORS.rst and AUTHORS.rst in the modules too? Otherwise building the credit part from manifest might be tricky.

[max3903]

Is it possible to also generate an index.html in the description directory? El lun., 16 de abr. de 2018 19:23, Eric @ Elico Corp < notifications@github.com> escribió:

…

Another point, probably implicit: the README should not be regenerated if no change happened in the doc directory either. I would add a section developer (optional) in your list but not essential indeed. Shall we think about introducing CONTRIBUTORS.rst and AUTHORS.rst in the modules too? Otherwise building the credit part from manifest might be tricky. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#335 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA5XsIDICz_89hSP3pLuROXn8xBm7zrfks5tpTYFgaJpZM4TWhLM> .

[sbidoul]

README should not be regenerated if no change happened

Of course

add a section developer (optional)

done

introducing CONTRIBUTORS.rst and AUTHORS.rst

My current thinking is that it's more flexible to let people write the whole credit section the way they please (except the maintainer part which will be generated). So they can add special credits (funders, thanks to my mom, etc) if they want to.

I'm also wondering if we should generate part of the README from the authors manifest key.

[sbidoul]

Is it possible to also generate an index.html in the description directory?

Yes, this opens up the possible to have a nicer presentation than what Odoo currently does when displaying the readme. That require a bit more thinking because people may want to keep control on the index.html to provide a more customized display.

[elicoidal]

@sbidoul Why am thinking about AUTHORS+CONTRIBUTORS file is because for the repository documentation (aggregated) we might end up with a mess if we do not restrict/limit the content of this files.

[elicoidal]

Maybe we need an additional credit file for other purposes (founders etc...)

[sbidoul]

Maybe we need an additional credit

Ok, I added contributors.rst and credits.rst. Authors would come from the manifest.

[elicoidal]

That require a bit more thinking because people may want to keep control on the index.html to provide a more customized display.

Do we need some kind of configuration checkbox somewhere? Auto-generate README.rst and Auto-generate HTML description (or better the opt-out one). Easy to do in the ERP with the github interface but looks complicated to maintain though

[sbidoul]

Auto-generate README.rst

This would be implicit as soon as introduction.rst and usage.rst are present.

I'd keep index.html generation for a second phase.

[lmignon]

@sbidoul I like you proposal. The generation of the 'index.html' file could help us to solve the annoying bug with images not properly displayed at same time into github, appstore and odoo/settings/modules odoo/odoo#8300

[dreispt]

Why multiple rst files instead of a single description.rst with multiple sections?

[elicoidal]

@dreispt the idea is to be able to combine the files into a README file for each module AND into a manual for the repository: this is why we need one file per section or concept in order to aggregate them properly at intermediate or higher level