Make OCA bot push docs

[yajo]

@sbidoul we can discuss here the implementation of the bot work.

Current plan:

• When a PR is merged, it should get to this repo and check if that module has docs.
• If there are no docs, then it should generate the module docs here directly.
• If it has docs, (or if it didn't have but now it has because of the previous step) then it should:
  • Remove these fragments:
    • CONFIGURE
    • CONTEXT
    • USAGE
    • DESCRIPTION
    • INSTALL
  • Add a basic DESCRIPTION fragment that just points to the docs URL. The URL must be written directly, so users browsing the README from Odoo Apps store can copy the URL and paste it in the browser (because they remove any links).

The goal is that the single source of truth for a module docs should be found here, but we wouldn't want to force developers to open 2 PRs when proposing a new module.

Notice that, when the PR alters the module behavior and thus the README needs an update, yes they will need to open 2 PRs. But the 2nd one can be done by someone else (hopefully a functional person).

[pedrobaeza]

I don't agree on removing the contents on the source module code. Modules must be self-contained, and don't require to go to an external site (supposing you have public Internet connection and the site is up, which both are not guaranteed), to look for a basic module documentation.

It's OK to push to "other place", but not to be destructive. I understand the fragmentation problem, but then what should be put is a synchronization mechanism between both systems (like with Weblate), not to strip out the contents in the source code.

[JordiBForgeFlow]

@yajo If the bot can both maintain the README and publish to an external site, that would be great. And the bot guarantees that the data stays in sync. Pretty much like the fragments and the README.

[yajo]

I think that giving you more context will help.

One goal here is to have a single version of the documentation. That way it'll be easier to manage for functional contributors.

The README in a module, however, is bound to the Odoo version it's built on. However, the docs site would have just a single version of the usage instructions.

I don't think it's appropriate or easy that the readme from here is pushed to all the readmes in all the module versions available. I don't think it's valuable to have information repeated in 2 different sources.

One possible solution would be to make the readme generator hide the fragments in the readme in case docs exist for the module. This way, the data stays in the fragments for those that want to consult it, but it's hidden in other places and replaced by a link to the docs. We considered this but we ended up believing that hiding things is less useful than just removing them and moving elsewhere.

If devs still see data within the module, they could believe that's the place where to contribute. However it won't be anymore once a module's readme is centralized here.

The modules must be self-contained, I agree. However, self-contained can perfectly mean that they contain a link to their docs site. For example, we already do that with license. We don't include it, but we put a link to it (in the modules; in repos we do copy it).

Having a single source of truth is good IMHO. DRY also. Syncs, however, are more complex to get done right. We wanted to start by something simpler, thus the current plan.

Hopefully you understand now that this part of the plan is among the most complex ones. Having all this context in mind, please feel free to suggest alternatives.

[francesco-ooops]

One goal here is to have a single version of the documentation. That way it'll be easier to manage for functional contributors.

Hi @yajo , this is something not really clear to me: I think "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile.

How would we manage to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right?

[pedrobaeza]

One goal here is to have a single version of the documentation.

That's simply undoable. Each Odoo version has its own UI, colors, fields distribution... and the most important things: its features. Each OCA module, depending on the Odoo version, will behave different. But not only that, each OCA module version will have their different features depending how it evolves on each branch (normally, the latest version having more features than the previous ones, but that's not guaranteed). Having only one version of the docs for all is worst than the current situation. For not talking about how to manage different conflicts of the pushed documentation between branches or making the developer/semi-functional people's life worst with all these troubles.

The solution to "hide" things is also not valid, as the README generator merges all of them, but also gives format and convert relative links to absolute ones to get the images rendered. If you want to guide functional people to contribute, it's as simple as putting a link on the header/foot going to the edition platform, the same as Odoo does:

As said, you may have a synchronization tool between both platforms. It's not valid to have outdated documentation on GitHub. And no way to have only one documentation source for all the versions. Even Odoo doesn't do that with their documentation, which is "more controlled".

[TumbaoJu]

One goal here is to have a single version of the documentation. That way it'll be easier to manage for functional contributors.

Hi @yajo , this is something not really clear to me: I think "active" versions of OCA modules are spanning about 4 versions (meaning: you can have someone employing v14 and someone on v18 at the same time), and it's very much possible some of these modules have gone through extensive refactoring in the meanwhile.

How would we manage to provide accurate documentation for all versions, or prevent an "edit war" where both users are in the right?

Hello @francesco-ooops . As discussed in the functional group, if a module has changes in the behavior in a version, the documentation should explain it. So you will have a section in the documentation (Context / Usage / Configuration) where you will explain from version x to version y, ... from version z ...

The idea is to find everything at the same place and not having to go and compare versions to see the changes.

[pedrobaeza]

@TumbaoJu please check my comment #7 (comment)

I see that almost impossible and worst for people contributing to the docs. Starting with, not everybody will check is something is done the same way across all the versions, and if something is "merged" without doing this cross-checking, you will have errors on the documentation that will confuse readers more than helping them.

[TumbaoJu]

Hello @pedrobaeza : From my experience, even if we actually have one Readme per version for a module, the Readme is not updated from version to version. It is the same (most of the time) for all versions.

Our idea is to mention in the documentation the version used and the difference in the Configuration, Usage by addind notes.

Example :

Documentation Odoo version : 16.0

• The behavior, configuration and usage are the same for all versions.

or

• Since version 14.0 ...

As a user of the OCA modules, I would have preferred to have all information in one page instead of going over each Readme in every version and see if something has changed.

We are trying here to help people find and use OCA modules more easily (having one documentation with all the information is easier for that) and to help non-technical persons contribute and make sure that is it as simple as it can be (the new tool is for that).

In the same idea, we want to reduce as much as possible the maintenance of this new tool and having a bidirectional synchronization is far more complicated than what was proposed.

Your help would be very welcome and I will be happy to talk to you about this new project if you want to ;)

[pedrobaeza]

The tool should fulfill the needs from both functional/technical, and this is only solving the functional part, so I don't agree with something ripping-off contents from source, sorry.

And about the version, I have already experienced some tests trying to merge all the versions into one, and they weren't successful. It's not true that migrating a module, the READMEs are not updated, nor adding a feature in version X. A lot of developers do that changes, but now if there's no way to even push that changes without conflicting, the situation will be worst, as you can't force people to go to other platform post-merge to update that documentation. Having one documentation per version + synchronization is the only way to get some success.

Reach me if you want more details about the catastrophes with this plan.

[francesco-ooops]

@yajo, @florenciafrigieri2, @TumbaoJu and @sbidoul: apart for the goal of centralization, what other reasons did you consider to exclude having different documentation per version?

[vdewulf]

hello here, I would like to get more feedback from the rest of the community, so I'll send an email to the contributors mailing list with the gathering of the different opinions here.

[NL66278]

I must say that I totally agree with @pedrobaeza . Both that modules should be self contained and that we should not have one version of the documentation for all versions of the module. The goal to help functional people to contribute to the documentation is lofty, but the way it is proposed to implement will lead to a drastic decline in the quality of documentation. Apart from the fact that a lot of technical people also contribute to the documentation, often of the features they themselves implement. Technical people would then be forced to use two completely separate methods to give their contribution.

Why not have a front end for functional people like the one proposed, but only storing the documentation on the original repository? Functional people could be offered just the latest version by default (with a button to switch to another version if they need to edit the documentation of a previous version). Any changes or additions made by functional people could just become a change commit applied to the original document, which should be a fragment in the readme directory.

[sbidoul]

Please let's keep the conversation on the mailing list so we have all arguments in one place. I'm going to lock this issue until a consensus or decision emerges.