Contributors mailing list archives
Re: Discover the OCA priorities for 2021 proposed by the boardby
Tecnativa. S. L., Jairo Llopis
I don't know but I feel like any standard solution won't work for us.
In a normal software project, you just have 1 branch (maybe 2: devel/stable). Then you add sphinx/mkdocs on a separate folder and docs live happily with your source code. Besides, those tools analyze your docstrings and autogenerate docs. Each repo contains 1 package, which has a single evolving version that follows a standard schema such as PEP 400, semver, calver, etc.
OCA has a workflow that is very alien to general github workflow:
- Code is spread across different repos.
- Each repo has different modules which can be tightly or loosely related among themselves and among modules that might exist in other repos.
- Each module has its own version. Which, BTW, means nothing in reality and follows a different schema imposed by Odoo and some OCA members.
- Each repo has multiple maintained versions of each module, one (or zero) per branch.
I think this is a deeply rooted problem across the whole OCA that hinders contributions and makes any move hard to achieve. I've tried to fix that in the past without success, so I don't care anymore. It's the OCA we have and I have to accept that.
So, having all that said, I think that the only way this could work is stick as it is: one README per module/version pair.
Odoo docs situation is today less crazy, so in case we have some functional stuff to document, if possible, the place to do it would be https://github.com/odoo/documentation
IMHO user docs should be avoided and, instead, modules should be self-explained within the UI. That goes through having friendly empty pages, tours, help tooltips, self-explained dialogs, res.config.settings dialogs, etc. Just make the module obvious and save documentation.
For other kind of cross-module, cross-repo, deployment, etc, kind of docs, possibly a single mkdocs repo could be deployed. As it wouldn't be coupled with any specific repo, odoo version or module, it wouldn't need any versioning or branching: just one main branch and build on each commit.
Coop IT Easy SC agréée, Virginie Dewulf