1. Mailing Lists
  2. Contributors
  3. OCA Functional Group - Project Modules Documentation

Contributors mailing list archives

contributors@odoo-community.org

Browse archives

multi company issue

tool: Odoo Modules Migration

Avatar

OCA Functional Group - Project Modules Documentation

by
NUMIGI Solutions Inc., Julie LeBrun
- 18/09/2023 16:08:43

After the last OCA Days in 2022, a group of functional people from different countries and companies decided to work together to improve functional contributions in OCA. 


Documentation of OCA modules has been identified as one of the main areas where functionals’ expertise can be useful. 


Our primary goals with this project are:

  • to make it easier for everyone to understand what is the purpose of a module and how to use it ;

  • to provide guidelines on how to write good and complete documentation ;

  • to improve access to editing and contribution of module’s documentation for functional people (eg: adding screenshots).


What are the changes?

  • Implementing Markdown in place of RST for Read Me

    • A great module documentation has screenshots so the reader can understand better how to use the module. The problem is that it is difficult for a functional person to add screenshots into an RST file.  You must upload the image in a folder (and you have to know which one ;) ), then you need to know how to put the link to the image, and if you make a mistake, the image doesn't show…

    • Markdown files are supported by GitHub and this format allows you to insert a screenshot easily by Drag & Drop.

    • Markdown provides a simple and unified layout (as RST do) so we don’t lose this advantage.

    • GitHub provides a Markdown editor tool so you don’t even have to learn the syntax (but, we tell you, it is very easy to learn ;) ) 

  • Providing guidelines for documentation

    • We are still working on the Guidelines but we will have a first version ready for the OCA days!

  • Enhancing Readme template

    • Adding some information into the description of the fragments so anybody (functional or developer) can understand the usage of each fragment.

    • Adding a new CONTEXT fragment. This new fragment can then be used to explain the why (context, use cases) of the module.


What are the impacts of those changes?

  • The Read Me’s template files have been converted to Markdown.

  • We will be converting, in the next weeks, all Read Me files to Markdown for all repositories in branch “16.0”. 

  • Read Me in RST will still be accepted but we strongly recommend to use Markdown for all the reasons enumerated previously.

  • For the branch “17.0”,  only Markdown files will be accepted.


How to proceed in case of migration of a module?

  • You can convert existing readme fragments from RST to Markdown for a whole repo using a command such as:

$ oca-gen-addon-readme --convert-fragments-to-markdown --org-name OCA --repo-name rest-framework --branch 16.0 --addons-dir . --gen-html


  • You can also convert an individual addon with --addon-dir (instead of --addons-dir) with a command like this:

$ oca-gen-addon-readme --convert-fragments-to-markdown --org-name OCA --repo-name purchase-workflow --branch 16.0 --addon-dir purchase_request --gen-html



How to proceed in case of pushing a new module into OCA?

  • Using the templates (which are now in Markdown)

  • And we recommend you follow the Guidelines!

    • We will be communicating about these Guidelines when they are ready!


We hope you enjoy these improvements!!!


The OCA Functional Group, Documentation Team

Julie LeBrun, Numigi Solutions

Francesco Foresti, ooops

Lara Freeke, Therp

Benedito Monteiro


Follow-Ups